A connection represents one end user’s authenticated session with an external provider through an integration. It stores the user’s credentials (OAuth tokens, API keys, etc.) securely and refreshes them automatically when needed.
Every connection belongs to an integration and is identified by a connection_id you assign (typically your internal user ID) plus the provider_config_key of its integration.
All API requests require a secret key passed as a Bearer token. You can find your secret key in the Settings section of the Nango dashboard.
List connections curl --request GET \ --url 'https://api.nango.dev/connections?connectionId=user-123&limit=20' \ --header 'Authorization: Bearer <SECRET_KEY>'
GET /connectionsReturns a paginated list of connections. You can filter by connection ID, end user, integration, and custom tags.
Query parameters Exact match on the connection ID. Can return multiple connections across different integrations if the same ID is used.
Filter by integration unique key (e.g. slack-production). Accepts a comma-separated list for multiple integrations.
Filter connections belonging to a specific end user ID.
Filter connections belonging to end users in a specific organization.
Search in connection ID or end user profile (name, email).
Maximum number of connections to return per page.
Page number for pagination (zero-indexed).
Response Internal numeric ID of the connection.
Your identifier for this connection (typically an end user ID).
The unique key of the integration this connection belongs to.
The provider slug (e.g. slack, github).
ISO 8601 timestamp of when the connection was created.
Custom metadata you have attached to this connection.
Key-value tags attached to this connection (e.g. end_user_id, end_user_email, organization_id).
Active errors on this connection (e.g. expired credentials). Each error has type and log_id.
The end user associated with this connection, if set.
{ "connections" : [ { "id" : 1 , "connection_id" : "user-123" , "provider" : "slack" , "provider_config_key" : "slack-production" , "created" : "2023-06-03T14:53:22.051Z" , "metadata" : null , "tags" : { "end_user_id" : "user-123" , "end_user_email" : "[email protected] " , "organization_id" : "org-456" }, "errors" : [], "end_user" : { "id" : "user-123" , "email" : "[email protected] " , "display_name" : "Alice" } }, { "id" : 2 , "connection_id" : "user-456" , "provider" : "slack" , "provider_config_key" : "slack-production" , "created" : "2023-06-03T15:00:14.945Z" , "metadata" : { "bot_id" : "B01234ABCDE" }, "tags" : { "end_user_id" : "user-456" , "end_user_email" : "[email protected] " }, "errors" : [{ "type" : "auth" , "log_id" : "VrnbtykXJFckCm3HP93t" }], "end_user" : null } ] }
Get a connection curl --request GET \ --url 'https://api.nango.dev/connections/user-123?provider_config_key=slack-production' \ --header 'Authorization: Bearer <SECRET_KEY>'
GET /connections/:connectionIdReturns a single connection including its live credentials. Nango automatically refreshes expired access tokens before returning the response.
Always fetch credentials just before you use them. Nango refreshes tokens on this call, so you always get a valid, non-expired credential.
The shape of the credentials field depends on the provider’s auth type (OAuth 2, OAuth 1, API key, Basic auth, etc.). Use the Proxy if you want Nango to inject credentials into requests for you. Path parameters The connection ID to retrieve.
Query parameters The unique key of the integration this connection belongs to. Required because the same connection_id can exist across multiple integrations.
Force a new token fetch from the provider even if the current token is still valid.
Include the refresh token in the response (OAuth 2 only).
refresh_github_app_jwt_token
Refresh the JWT token for GitHub App or GitHub App OAuth connections.
Response Internal numeric ID of the connection.
Your identifier for this connection.
The integration’s unique key.
The provider slug (e.g. slack).
Provider-specific connection configuration set during auth (e.g. subdomain, instance URL).
Custom metadata you have attached to this connection.
Key-value tags attached to this connection.
The live credentials for this connection. Shape depends on auth type. The current access token.
Present only when refresh_token=true is passed.
ISO 8601 expiry time of the access token.
The full raw token response from the provider.
The OAuth 1.0a access token.
The OAuth 1.0a token secret.
The full raw token response from the provider.
Active errors on this connection.
ISO 8601 creation timestamp.
ISO 8601 last-updated timestamp.
Example response (OAuth 2)
{ "id" : 1 , "connection_id" : "user-123" , "provider_config_key" : "slack-production" , "provider" : "slack" , "connection_config" : {}, "metadata" : { "workspace_id" : "T01234ABCDE" }, "tags" : { "end_user_id" : "user-123" , "end_user_email" : "[email protected] " }, "credentials" : { "type" : "OAUTH2" , "access_token" : "xoxp-1234567890-abcdefghij" , "expires_at" : "2024-01-15T11:30:00.000Z" , "raw" : { "ok" : true , "access_token" : "xoxp-1234567890-abcdefghij" , "token_type" : "Bearer" , "scope" : "channels:read,chat:write" } }, "errors" : [], "created_at" : "2024-01-15T10:30:00.000Z" , "updated_at" : "2024-01-15T11:29:58.000Z" }
Import a connection curl --request POST \ --url https://api.nango.dev/connections \ --header 'Authorization: Bearer <SECRET_KEY>' \ --header 'Content-Type: application/json' \ --data '{ "connection_id": "user-123", "provider_config_key": "github-prod", "credentials": { "type": "OAUTH2", "access_token": "gho_existingtoken", "refresh_token": "ghr_existingrefreshtoken", "expires_at": "2024-12-31T23:59:59.000Z" }, "metadata": { "github_username": "alice" } }'
POST /connectionsImports existing credentials into Nango without going through an OAuth flow. Use this for bulk migrations when onboarding to Nango.
This endpoint is intended for one-off bulk imports of existing tokens. For new connections, use the Connect UI or the frontend SDK to run the OAuth flow. Request body The unique key of the integration to create the connection under.
Your identifier for this connection. If omitted, Nango generates one.
The credentials to import. The required fields depend on the provider’s auth type. Existing refresh token (recommended).
ISO 8601 expiry of the access token.
Custom metadata to attach to the connection.
Provider-specific configuration (e.g. subdomain, instance_url).
End user to associate with this connection. Key-value tags to attach to the connection (e.g. { "plan": "enterprise" }).
Response Returns the created connection object including its credentials. See Get a connection for the full response shape.
Update a connection curl --request PATCH \ --url 'https://api.nango.dev/connections/user-123?provider_config_key=slack-production' \ --header 'Authorization: Bearer <SECRET_KEY>' \ --header 'Content-Type: application/json' \ --data '{ "end_user": { "id": "user-123", "email": "[email protected] ", "display_name": "Alice Smith" }, "tags": { "plan": "enterprise", "organization_id": "org-456" } }'
PATCH /connections/:connectionIdUpdates the end user profile or tags on a connection. Does not modify credentials.
Path parameters The connection ID to update.
Query parameters The unique key of the integration this connection belongs to.
Request body Updated end user information to associate with this connection. Key-value tags to set on the connection. This replaces the existing tag set.
Response Delete a connection curl --request DELETE \ --url 'https://api.nango.dev/connections/user-123?provider_config_key=slack-production' \ --header 'Authorization: Bearer <SECRET_KEY>'
DELETE /connections/:connectionIdPermanently deletes a connection and its stored credentials.
Path parameters The connection ID to delete.
Query parameters The unique key of the integration this connection belongs to.
Response curl --request POST \ --url https://api.nango.dev/connections/metadata \ --header 'Authorization: Bearer <SECRET_KEY>' \ --header 'Content-Type: application/json' \ --data '{ "connection_id": "user-123", "provider_config_key": "slack-production", "metadata": { "workspace_id": "T01234ABCDE", "bot_id": "B09876ZYXWV" } }'
POST /connections/metadataReplaces the metadata on one or more connections entirely. Existing metadata is overwritten.
This replaces the entire metadata object. Use Update metadata (PATCH) to merge changes without overwriting existing keys. Request body connection_id
string | string[]
required
The connection ID to update, or an array of connection IDs to update in bulk.
The unique key of the integration the connection(s) belong to.
The new metadata to set. Must be a JSON object. All existing metadata keys are replaced.
Response Returns the body you sent as confirmation.
{ "connection_id" : "user-123" , "provider_config_key" : "slack-production" , "metadata" : { "workspace_id" : "T01234ABCDE" , "bot_id" : "B09876ZYXWV" } }
curl --request PATCH \ --url https://api.nango.dev/connections/metadata \ --header 'Authorization: Bearer <SECRET_KEY>' \ --header 'Content-Type: application/json' \ --data '{ "connection_id": "user-123", "provider_config_key": "slack-production", "metadata": { "bot_id": "B-NEW-VALUE" } }'
PATCH /connections/metadataMerges the provided metadata into the connection’s existing metadata. Only the keys you provide are updated; all other keys remain unchanged.
Request body connection_id
string | string[]
required
The connection ID to update, or an array of connection IDs to update in bulk.
The unique key of the integration the connection(s) belong to.
The metadata keys to update. Only these keys are changed; existing keys not included here are preserved.
Response Returns the body you sent as confirmation.
{ "connection_id" : "user-123" , "provider_config_key" : "slack-production" , "metadata" : { "bot_id" : "B-NEW-VALUE" } }
To read a connection’s metadata, fetch the connection using Get a connection . The metadata field is included in the response.
import { Nango } from '@nangohq/node' ; const nango = new Nango ({ secretKey: '<SECRET_KEY>' }); const metadata = await nango . getMetadata ( 'slack-production' , 'user-123' ); // Returns: { workspace_id: "T01234ABCDE", bot_id: "B09876ZYXWV" }
