Learn to create and manage access tokens for Import API sources using the Connect API.


Prerequisites


Import API access tokens and destination schemas

Import API access tokens are specific to the Import API source they are created for. This means that data successfully pushed using a given Import API access token will only ever be loaded into the schema or dataset created for that source.

For example: You create an Import API source named Customer Records, which has a corresponding destination schema named customer_records. Any data pushed to the Import API made using the access token associated with the Customer Records source will only affect the data in the customer_records schema.

Each Import API source is allowed a maximum of two active API access tokens at a time. This ensures that you can rotate your Import API access tokens when needed without interrupting replication.

Refer to the Import API authentication reference for more info.


Generate an Import API access token

In this section:

Step Action Endpoint
1 Retrieve the Import API source's ID GET /v4/sources
2 Create the access token POST /v4/sources/{source_id}/tokens

Step 1: Retrieve the Import API source's ID

If you’re logged into Stitch, you can locate the ID of your Import API source by clicking into the integration and looking at its URL. The number between connections/ and /summary in the URL is the source ID:

The Stitch app in a web browser, with the source ID highlighted in the URL.

In this example, the source ID is 216359.

Otherwise, you can use the GET /v4/sources endpoint to get a list of the current Stitch account’s sources:

GET /v4/sources
curl "https://api.stitchdata.com/v4/sources" \
     -H 'Authorization: Bearer [ACCESS_TOKEN]' \
     -H 'Content-Type: application/json'

The response will be an array of Source objects. Locate the Import API source you want to use, and take note of its id value:

Response for GET /v4/sources
[
  {
    ...
  },
  {
    "properties": {},
    "updated_at": "2020-01-21T22:38:21Z",
    "schedule": null,
    "name": "import_api_tokens_example",
    "type": "import_api",
    "deleted_at": null,
    "system_paused_at": null,
    "stitch_client_id": 116078,
    "paused_at": null,
    "id": 216359,                                 /* Source ID */
    "display_name": "Import API tokens example",
    "created_at": "2020-01-21T22:38:21Z",
    "report_card": {
      "type": "import_api",
      "current_step": 2,
      "current_step_type": "fully_configured",
      "steps": [
        {
          "type": "form",
          "properties": []
        },
        {
          "type": "fully_configured",
          "properties": []
        }
      ]
    }
  },
  {
    ...
  }
]

Step 2: Create the access token

Using the Import API source’s ID, make a request to POST /v4/sources/{source_id}/tokens, replacing {source_id} with the ID of the Import API source. In this example, the ID is 216359:

POST /v4/sources/{source_id}/tokens
curl -X "POST" "https://api.stitchdata.com/v4/sources/216359/tokens" \
     -H 'Authorization: Bearer [ACCESS_TOKEN]' \
     -H 'Content-Type: application/json'

The response will be an Import API access token object with an access_token property. The value of this property is the access token you’ll need to include in requests made to the Import API:

Response for POST /v4/sources/{source_id}/tokens
{
  "id": 828704779,
  "access_token": "<IMPORT_API_ACCESS_TOKEN>"
}

Note: The API will only return the Import API access token once, immediately after generation. Store the access token and its ID somewhere secure, as you’ll need the access token ID to revoke the token.


Rotate Import API access tokens

If you need to revoke an Import API access token, we recommend first creating a second token and updating your application with it to prevent interruptions. Note: Any requests you attempt to send to Stitch during the time an invalid token is in use must be re-sent once valid a token is in place.

In this section:

Step Action Endpoint
1 Retrieve the Import API source's ID GET /v4/sources
2 Create a new Import API access token POST /v4/sources/{source_id}/tokens
3 Retrieve the Import API access token IDs GET /v4/sources/{source_id}/tokens
4 Update your Import API credentials
5 Revoke the original Import API access token DELETE /v4/sources/{source_id}/tokens/{token_id}
6 Verify the access token revocation GET /v4/sources/{source_id}/tokens

Step 1: Retrieve the Import API source's ID

If you’re logged into Stitch, you can locate the ID of your Import API source by clicking into the integration and looking at its URL. The number between connections/ and /summary in the URL is the source ID:

The Stitch app in a web browser, with the source ID highlighted in the URL.

In this example, the source ID is 216359.

Otherwise, you can use the GET /v4/sources endpoint to get a list of the current Stitch account’s sources:

GET /v4/sources
curl "https://api.stitchdata.com/v4/sources" \
     -H 'Authorization: Bearer [ACCESS_TOKEN]' \
     -H 'Content-Type: application/json'

The response will be an array of Source objects. Locate the Import API source you want to use, and take note of its id value:

Response for GET /v4/sources
[
  {
    ...
  },
  {
    "properties": {},
    "updated_at": "2020-01-21T22:38:21Z",
    "schedule": null,
    "name": "import_api_tokens_example",
    "type": "import_api",
    "deleted_at": null,
    "system_paused_at": null,
    "stitch_client_id": 116078,
    "paused_at": null,
    "id": 216359,                                 /* Source ID */
    "display_name": "Import API tokens example",
    "created_at": "2020-01-21T22:38:21Z",
    "report_card": {
      "type": "import_api",
      "current_step": 2,
      "current_step_type": "fully_configured",
      "steps": [
        {
          "type": "form",
          "properties": []
        },
        {
          "type": "fully_configured",
          "properties": []
        }
      ]
    }
  },
  {
    ...
  }
]

Step 2: Create a new Import API access token

Before you revoke the original access token, we recommend generating a new one to take its place. This will minimize disruptions to replication while you update your Import API credentials.

Using the Import API source’s ID, make a request to POST /v4/sources/{source_id}/tokens, replacing {source_id} with the ID of the Import API source. In this example, the ID is 216359:

POST /v4/sources/{source_id}/tokens
curl -X "POST" "https://api.stitchdata.com/v4/sources/216359/tokens" \
     -H 'Authorization: Bearer [ACCESS_TOKEN]' \
     -H 'Content-Type: application/json'

The response will be an Import API access token object with an access_token property. The value of this property is the access token you’ll need to include in requests made to the Import API:

Response for POST /v4/sources/{source_id}/tokens
{
  "id": 828705046,
  "access_token": "<IMPORT_API_ACCESS_TOKEN>"
}

Step 3: Retrieve the Import API access token IDs

Using the Import API source’s ID, make a request to GET /v4/sources/{source_id}/tokens, replacing {source_id} with the ID of the Import API source. In this example, the ID is 216359:

GET /v4/sources/{source_id}/tokens
curl "https://api.stitchdata.com/v4/sources/216359/tokens" \
     -H 'Authorization: Bearer [ACCESS_TOKEN]' \
     -H 'Content-Type: application/json'

The response will be an array containing the IDs of the access tokens associated with the specified Import API source ID:

Response for GET /v4/sources/{source_id}/tokens
[
  828705046,            /* New token ID */
  828704779             /* Original token ID */
]

Import API Access token IDs are auto-incrementing, meaning their values will only increase. The ID with the greater value is the ID for the newer access token. In this example, the ID for the new access token would be 828705046.

Store the ID for the new access token somewhere secure, in case you need to revoke it at a later point.

Keep the ID of the original access token (828704779) handy - you’ll need it to complete the last step in this guide.

Step 4: Update your Import API credentials

Before continuing, update your application with the new Import API access token you generated in Step 2.

Step 5: Revoke the original Import API access token

Make a request to DELETE /v4/sources/{source_id}/tokens/{token_id}, replacing {source_id} with the source ID and {token_id} with the ID of the access token to be revoked.

In this example, that would be 216359 and 828704779, respectively:

DELETE /v4/sources/{source_id}/tokens/{token_id}
curl -X "DELETE" "https://api.stitchdata.com/v4/sources/216359/tokens/828704779" \
     -H 'Authorization: Bearer [ACCESS_TOKEN]' \
     -H 'Content-Type: application/json'

If successful, the response will be a Source object with an updated updated_at value:

Response for DELETE /v4/sources/{source_id}/tokens/{token_id}
{
  "properties": {},
  "updated_at": "2020-01-22T09:40:32Z",
  "schedule": null,
  "name": "import_api_tokens_example",
  "type": "import_api",
  "deleted_at": null,
  "system_paused_at": null,
  "stitch_client_id": 116078,
  "paused_at": null,
  "id": 216359,
  "display_name": "Import API tokens example",
  "created_at": "2020-01-21T22:38:21Z",
  "report_card": {
    "type": "import_api",
    "current_step": 2,
    "current_step_type": "fully_configured",
    "steps": [
      {
        "type": "form",
        "properties": []
      },
      {
        "type": "fully_configured",
        "properties": []
      }
    ]
  }
}

Step 6: Verify the access token revocation

Additionally, you can verify that the access token has been successfully revoked by checking the access token IDs associated with the Import API source.

Using the Import API source’s ID, make a request to GET /v4/sources/{source_id}/tokens, replacing {source_id} with the ID of the Import API source. In this example, the ID is 216359:

GET /v4/sources/{source_id}/tokens
curl "https://api.stitchdata.com/v4/sources/216359/tokens" \
     -H 'Authorization: Bearer [ACCESS_TOKEN]' \
     -H 'Content-Type: application/json'

The response should only contain the ID for the new access token:

Response for GET /v4/sources/{source_id}/tokens
[
  828705046
]