> ## Documentation Index
> Fetch the complete documentation index at: https://nango.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Import a connection

> Upserts a connection for which you already have credentials.

<Info>
  Requires an API key with the `environment:connections:create` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
</Info>

## When to use

Use this API endpoint to import existing access tokens into Nango. It is mostly meant for one-off bulk imports when onboarding Nango, or for migrating existing connections when a provider introduced changes to its auth flow.

If a connection with the same `connection_id` and `provider_config_key` already exists, the endpoint updates it with the provided credentials instead of creating a new one.

To trigger OAuth flows with Nango, use the [Nango frontend SDK](/reference/frontend/frontend-sdk).

## Request body

You can use this endpoint to import OAuth 2, OAuth 1, API Keys, and Basic auth credentials.

The required fields depend on the type of authentication of the *connections* you are trying to import.


## OpenAPI

````yaml POST /connections
openapi: 3.1.0
info:
  title: Nango API
  description: Nango API specs used to authorize & sync data with external APIs.
  version: 1.0.0
servers:
  - url: https://api.nango.dev
    description: Production server
  - url: http://localhost:3003
    description: Local server
security:
  - bearerAuth: []
externalDocs:
  url: https://nango.dev/docs/reference/backend/http-api/authentication
paths:
  /connections:
    post:
      summary: Upsert a connection
      description: Upserts a connection for which you already have credentials.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - provider_config_key
                - credentials
              properties:
                provider_config_key:
                  type: string
                  description: The integration ID that you created on Nango.
                metadata:
                  type: object
                  description: >-
                    (OAuth, required for some APIs) Metadata to be attached to
                    the connection.
                connection_id:
                  type: string
                  description: The connection ID used to create the connection.
                connection_config:
                  type: object
                  description: >-
                    (OAuth, required for some APIs) Additional configuration to
                    be attached to the connection.
                credentials:
                  type: object
                  description: The credentials to be attached to the connection.
                  anyOf:
                    - $ref: '#/components/schemas/OAuth1Credentials'
                    - $ref: '#/components/schemas/OAuth2Credentials'
                    - $ref: '#/components/schemas/BasicApiCredentials'
                    - $ref: '#/components/schemas/ApiKeyCredentials'
                    - $ref: '#/components/schemas/OAuth2ClientCredentials'
                    - $ref: '#/components/schemas/UnauthCredentialsWithType'
                    - $ref: '#/components/schemas/TbaCredentials'
                    - type: object
                      title: GitHub App
                      additionalProperties: false
                      required:
                        - type
                        - app_id
                        - installation_id
                      properties:
                        type:
                          type: string
                          enum:
                            - APP
                        app_id:
                          type: string
                        installation_id:
                          type: string
                tags:
                  $ref: '#/components/schemas/Tags'
                end_user:
                  allOf:
                    - $ref: '#/components/schemas/EndUser'
                  deprecated: true
                  description: Deprecated, use tags instead
      responses:
        '200':
          description: Successfully created an integrations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionFull'
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  schemas:
    OAuth1Credentials:
      type: object
      title: OAuth1
      additionalProperties: false
      properties:
        oauth_token:
          type: string
        oauth_token_secret:
          type: string
        type:
          enum:
            - OAUTH1
          type: string
      required:
        - oauth_token
        - oauth_token_secret
        - type
    OAuth2Credentials:
      type: object
      title: OAuth2
      additionalProperties: false
      properties:
        access_token:
          type: string
        config_override:
          additionalProperties: false
          properties:
            client_id:
              type: string
            client_secret:
              type: string
          type: object
        expires_at:
          type: string
          format: date-time
        refresh_token:
          type: string
        type:
          enum:
            - OAUTH2
          type: string
      required:
        - access_token
        - type
    BasicApiCredentials:
      type: object
      title: Basic Auth
      additionalProperties: false
      properties:
        password:
          type: string
        type:
          enum:
            - BASIC
          type: string
        username:
          type: string
      required:
        - type
        - username
        - password
    ApiKeyCredentials:
      type: object
      title: Api Key
      additionalProperties: false
      properties:
        apiKey:
          type: string
        type:
          type: string
          enum:
            - API_KEY
      required:
        - type
        - apiKey
    OAuth2ClientCredentials:
      type: object
      title: OAuth2 Client
      additionalProperties: false
      properties:
        client_id:
          type: string
        client_secret:
          type: string
        expires_at:
          type: string
          format: date-time
        token:
          type: string
        type:
          type: string
          enum:
            - OAUTH2_CC
      required:
        - client_id
        - client_secret
        - token
        - type
    UnauthCredentialsWithType:
      type: object
      title: Unauthenticated
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - NONE
    TbaCredentials:
      type: object
      title: TBA
      additionalProperties: false
      properties:
        config_override:
          additionalProperties: false
          properties:
            client_id:
              type: string
            client_secret:
              type: string
          type: object
        token_id:
          type: string
        token_secret:
          type: string
        type:
          type: string
          enum:
            - TBA
      required:
        - type
        - token_id
        - token_secret
        - config_override
    Tags:
      type: object
      description: Connection tags (key/value strings). Keys are normalized to lowercase.
      maxProperties: 10
      additionalProperties:
        type: string
        maxLength: 255
    EndUser:
      type: object
      deprecated: true
      required:
        - id
      properties:
        id:
          type: string
          description: Uniquely identifies the end user.
          deprecated: true
        email:
          type: string
          deprecated: true
        display_name:
          type: string
          deprecated: true
        tags:
          type: object
          additionalProperties:
            type: string
            maxLength: 64
          description: >-
            Tags associated with the end user. Only accepts strings values, up
            to 64 keys.
          deprecated: true
    ConnectionFull:
      type: object
      required:
        - id
        - connection_id
        - provider_config_key
        - provider
        - errors
        - metadata
        - connection_config
        - tags
        - created_at
        - updated_at
        - last_fetched_at
        - credentials
      properties:
        id:
          type: integer
        connection_id:
          type: string
        provider_config_key:
          type: string
        provider:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ConnectionError'
        end_user:
          deprecated: true
          anyOf:
            - $ref: '#/components/schemas/ConnectionEndUser'
            - type: 'null'
        metadata:
          type: object
          additionalProperties: true
        connection_config:
          type: object
          additionalProperties: true
        tags:
          $ref: '#/components/schemas/Tags'
        created_at:
          type: string
        updated_at:
          type: string
        last_fetched_at:
          type: string
        credentials:
          $ref: '#/components/schemas/AllAuthCredentials'
    ConnectionError:
      type: object
      required:
        - type
        - log_id
      properties:
        type:
          type: string
          enum:
            - auth
            - sync
          example: auth
        log_id:
          type: string
          example: VrnbtykXJFckCm3HP93t
    ConnectionEndUser:
      type: object
      deprecated: true
      required:
        - id
      properties:
        id:
          type: string
          description: Uniquely identifies the end user.
          deprecated: true
        email:
          anyOf:
            - type: string
            - type: 'null'
          deprecated: true
        display_name:
          anyOf:
            - type: string
            - type: 'null'
          deprecated: true
        tags:
          type: object
          additionalProperties: true
          description: >-
            Tags associated with the end user. Only accepts strings values, up
            to 64 keys.
          deprecated: true
        organization:
          deprecated: true
          anyOf:
            - type: object
              required:
                - id
              properties:
                id:
                  type: string
                  description: Uniquely identifies the organization the end user belongs to
                display_name:
                  anyOf:
                    - type: string
                    - type: 'null'
            - type: 'null'
    AllAuthCredentials:
      anyOf:
        - $ref: '#/components/schemas/OAuth1CredentialsWithRaw'
        - $ref: '#/components/schemas/OAuth2CredentialsWithRaw'
        - $ref: '#/components/schemas/BasicApiCredentials'
        - $ref: '#/components/schemas/ApiKeyCredentials'
        - $ref: '#/components/schemas/AppCredentials'
        - $ref: '#/components/schemas/JwtCredentials'
        - $ref: '#/components/schemas/OAuth2ClientCredentialsWithRaw'
        - $ref: '#/components/schemas/AppStoreCredentialsWithRaw'
        - $ref: '#/components/schemas/UnauthCredentials'
        - $ref: '#/components/schemas/CustomCredentials'
        - $ref: '#/components/schemas/TbaCredentials'
        - $ref: '#/components/schemas/BillCredentialsWithRaw'
        - $ref: '#/components/schemas/TwoStepCredentials'
        - $ref: '#/components/schemas/SignatureCredentials'
    StdError:
      type: object
      additionalProperties: false
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
          properties:
            code:
              type: string
            message:
              type: string
            errors:
              type: array
              items:
                type: object
    OAuth1CredentialsWithRaw:
      title: OAuth1
      allOf:
        - $ref: '#/components/schemas/OAuth1Credentials'
        - type: object
          additionalProperties: false
          required:
            - raw
          properties:
            raw:
              type: object
    OAuth2CredentialsWithRaw:
      title: OAuth2
      allOf:
        - $ref: '#/components/schemas/OAuth2Credentials'
        - type: object
          additionalProperties: false
          required:
            - raw
          properties:
            raw:
              type: object
    AppCredentials:
      type: object
      title: GitHub App
      additionalProperties: false
      properties:
        access_token:
          type: string
        expires_at:
          type: string
          format: date-time
        raw:
          type: object
        type:
          type: string
          enum:
            - APP
      required:
        - type
        - access_token
        - raw
    JwtCredentials:
      type: object
      title: JWT
      additionalProperties: false
      properties:
        expires_at:
          type: string
          format: date-time
        issuerId:
          type: string
        privateKey:
          anyOf:
            - additionalProperties: false
              properties:
                id:
                  type: string
                secret:
                  type: string
              required:
                - id
                - secret
              type: object
            - type: string
        privateKeyId:
          type: string
        token:
          type: string
        type:
          type: string
          enum:
            - JWT
      required:
        - type
        - privateKey
    OAuth2ClientCredentialsWithRaw:
      title: OAuth2 Client
      allOf:
        - $ref: '#/components/schemas/OAuth2ClientCredentials'
        - type: object
          additionalProperties: false
          required:
            - raw
          properties:
            raw:
              type: object
    AppStoreCredentialsWithRaw:
      title: App Store
      allOf:
        - $ref: '#/components/schemas/AppStoreCredentials'
        - type: object
          additionalProperties: false
          required:
            - raw
          properties:
            raw:
              type: object
    UnauthCredentials:
      type: object
      title: Unauthenticated
      additionalProperties: false
    CustomCredentials:
      type: object
      title: Custom
      additionalProperties: false
      properties:
        raw:
          type: object
        type:
          type: string
          enum:
            - CUSTOM
      required:
        - raw
        - type
    BillCredentialsWithRaw:
      title: Bill
      allOf:
        - $ref: '#/components/schemas/BillCredentials'
        - type: object
          additionalProperties: false
          required:
            - raw
          properties:
            raw:
              type: object
    TwoStepCredentials:
      type: object
      title: Two Step
      additionalProperties: false
      properties:
        expires_at:
          type: string
          format: date-time
        raw:
          type: object
        token:
          type: string
        type:
          type: string
          enum:
            - TWO_STEP
      required:
        - raw
        - type
    SignatureCredentials:
      type: object
      title: Signature
      additionalProperties: false
      properties:
        expires_at:
          type: string
          format: date-time
        password:
          type: string
        token:
          type: string
        type:
          type: string
          enum:
            - SIGNATURE
        username:
          type: string
      required:
        - type
        - username
        - password
    AppStoreCredentials:
      type: object
      title: App Store
      additionalProperties: false
      properties:
        access_token:
          type: string
        expires_at:
          type: string
          format: date-time
        private_key:
          type: string
        type:
          type: string
          enum:
            - APP_STORE
      required:
        - access_token
        - private_key
    BillCredentials:
      type: object
      title: Bill
      additionalProperties: false
      properties:
        dev_key:
          type: string
        expires_at:
          type: string
          format: date-time
        organization_id:
          type: string
        password:
          type: string
        session_id:
          type: string
        type:
          type: string
          enum:
            - BILL
        user_id:
          type: string
        username:
          type: string
      required:
        - dev_key
        - organization_id
        - password
        - raw
        - type
        - username
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StdError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: The secret key from your Nango environment.

````