> ## Documentation Index > Fetch the complete documentation index at: https://docs.fly.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a custom API connector > Create a connector for any token-authenticated HTTP API. The connector's `name` is its identity within the organization: creating another custom API connector with the same name updates that connector in place instead of adding a second one. Creating does not test the credential; use the test endpoint for that. Requires full access. ## OpenAPI ````yaml /sprites/api/openapi.json post /v1/oauth/connections/custom_api openapi: 3.1.0 info: title: Sprites API version: 0.1.12 x-sprite-env-version: 0.0.5 servers: - url: https://api.sprites.dev security: [] paths: /v1/oauth/connections/custom_api: post: tags: - Connectors summary: Create a custom API connector description: >- Create a connector for any token-authenticated HTTP API. The connector's `name` is its identity within the organization: creating another custom API connector with the same name updates that connector in place instead of adding a second one. Creating does not test the credential; use the test endpoint for that. Requires full access. operationId: o_auth_connections_create_custom_api_post parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CustomApiConnectionRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/ConnectionResponse' description: Created '400': description: Invalid request parameters '401': description: Missing or invalid authentication '403': description: Full access required '422': description: Connector could not be stored security: - bearerAuth: [] components: schemas: CustomApiConnectionRequest: description: Custom API connector request properties: access_policy: $ref: '#/components/schemas/AccessPolicy' description: >- Initial access policy. Empty or missing policies deny sprite use until updated. example: allow_all: true access_token: description: >- Credential sent to the provider. Stored encrypted and never returned by the API. example: sk-live-... type: string auth_custom_header_name: description: >- Header that carries the credential when `auth_method` is `custom_header`. Defaults to `X-Api-Key`. Reserved hop-by-hop and identity headers are rejected. example: X-Api-Key type: string auth_header_prefix: description: >- Prefix for the `Authorization` header value when `auth_method` is `header`. Defaults to `Bearer`. An empty string sends the bare credential. example: Bearer type: string auth_method: description: >- Where the credential is placed on provider requests. `header` sends an `Authorization` header prefixed by `auth_header_prefix`; `url_path` substitutes it into `auth_url_path_template`; `query_param` adds it as the `auth_query_param_name` query parameter; `custom_header` sends it as the `auth_custom_header_name` header. Defaults to `header`. enum: - header - url_path - query_param - custom_header example: header type: string auth_query_param_name: description: >- Query parameter that carries the credential when `auth_method` is `query_param`. Defaults to `api_key`. example: api_key type: string auth_url_path_template: description: >- Path segment inserted between `base_api_url` and the requested path when `auth_method` is `url_path`. `{token}` is replaced with the credential. example: /bot{token} type: string base_api_url: description: >- Base URL of the provider API. Gateway paths are appended to it when a sprite calls the connector. example: https://api.acme.example type: string description: description: Free-form description shown in the dashboard. example: Acme production account type: string name: description: >- Connector name. This is the connector's unique identity within the organization: creating a second custom API connector with the same name updates the existing connector in place rather than creating another one. example: acme-api type: string refresh_token: description: >- Optional refresh token stored alongside the credential. Stored encrypted and never returned. example: rt-... type: string test_url: description: >- URL the connector test fetches with the credential attached. For `auth_method` `url_path` give a path relative to `base_api_url` (such as `/me`), because the test joins `base_api_url`, the token path and this value; for every other method give an absolute URL. Stored for later tests; creating a connector does not run the test. example: https://api.acme.example/me type: string required: - name - base_api_url - access_token type: object ConnectionResponse: description: Connector response properties: connection: $ref: '#/components/schemas/Connection' description: >- Sanitized connector. Secrets and encrypted token fields are never returned. example: id: conn_abc123 provider: slack required: - connection type: object AccessPolicy: description: Connector access policy properties: allow_all: description: When true, all sprites in the organization may use this connector. example: false type: boolean allowed_endpoints: description: >- HTTP provider API paths the connector may call. Supports exact paths and trailing `*` prefix wildcards. Database connectors reject endpoint rules. example: - /chat.* items: type: string type: array blocked_endpoints: description: >- HTTP provider API paths the connector may not call, matched without regard to case. Block rules are checked before allow rules. Database connectors reject endpoint rules. example: - /admin.* items: type: string type: array name_prefix: description: Sprite name prefix required to use this connector. example: prod- type: string sprite_labels: description: Labels the calling sprite must have. All listed labels are required. example: - api-access items: type: string type: array required: [] type: object Connection: description: Connector properties: access_policy: $ref: '#/components/schemas/AccessPolicy' description: >- Policy controlling which sprites and provider endpoints may use this connector. example: allow_all: true allowed_endpoints: - /* connection_type: description: How the connector was created. enum: - oauth - api_key - provisioned - internal - database example: oauth type: string id: description: >- Connector ID used in HTTP gateway URLs or as a native database selector. example: conn_abc123 type: string inserted_at: description: When the connector was created. example: '2026-04-28T12:00:00Z' format: date-time type: string native_connection_uri: description: >- Credential-free PostgreSQL URI when native ingress is available; otherwise null. Use Sprite discovery for runtime-specific details. type: - string - 'null' notes: description: >- Provider notes about this connection, derived from its saved settings. example: - body: Full-access key. title: null items: $ref: '#/components/schemas/ProviderNote' type: array postgres: $ref: '#/components/schemas/PostgresDescriptor' description: >- S2 native descriptor: available, host, port, database, non-secret selector username, sslmode and protection. Legacy S1 and unspecified Sprites have no usable endpoint. provider: description: >- Provider key. See https://fly.io/sprites/ecosystem/ for current connectors. example: slack type: string provider_account_id: description: Provider account, workspace, or key identifier. example: T12345 type: string provider_account_name: description: Human-readable provider account name. example: Example Workspace type: string provider_info: description: >- Public provider settings such as workspace URLs, database targets and auth_generation, custom API base URLs, or icon references. Credentials are excluded. example: team_domain: example type: object scopes: description: Comma-separated OAuth scopes granted to the connector. example: chat:write,channels:read type: string token_expires_at: description: >- When the stored token expires, if the provider issues expiring tokens. example: '2026-04-29T12:00:00Z' format: date-time type: string transport: description: The wire protocol this connector requires. enum: - http - postgres type: string updated_at: description: When the connector was last updated. example: '2026-04-29T12:00:00Z' format: date-time type: string usage_snippet: description: >- Provider-specific HTTP curl snippet using the connector gateway origin, or native PostgreSQL usage. Null when native ingress is unavailable. example: curl https://api.sprites.dev/v1/gateway/slack/conn_abc123/auth.test type: - string - 'null' user_id: description: Sprites user ID that created or owns the connector. example: user_abc123 type: string required: - id - provider - provider_account_id type: object ProviderNote: description: Connector provider note properties: body: description: Note body. Backticks mark inline code. type: string title: description: Note title. type: - string - 'null' required: - body type: object PostgresDescriptor: description: Native PostgreSQL descriptor properties: available: description: >- Whether this S2 Sprite has enabled native routing. False for legacy S1 Sprites. type: boolean database: description: The immutable saved database name. type: string host: description: >- S2 internal connector hostname, or null for unsupported or unspecified Sprites. type: - string - 'null' port: description: Native ingress port. type: integer protection: description: Transport protecting the Sprite's SQL bytes. enum: - authenticated_platform_tunnel type: string sslmode: description: >- The S2 platform tunnel protects guest traffic; upstream TLS is always verified. enum: - disable type: string username: description: Non-secret connector selector, not the upstream SQL role. type: string required: - available - host - port - database - username - sslmode - protection type: object securitySchemes: bearerAuth: scheme: bearer type: http ````