Managing and Revoking Import API Access Tokens via the Connect API

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

Prerequisites

• Access to Stitch Connect and valid Connect API credentials. Connect access is a Stitch Advanced or Premium feature. Refer to the Connect API reference for more info on obtaining API credentials.

• An existing Import API source. This guide assumes you’ve already created an Import API source, either in Stitch or using the Connect API. If you haven’t, create one before continuing by using one of the following guides:

  • Create and configure an Import API source with the Connect API
  • Create an Import API integration in Stitch

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 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:

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:

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:

[
  {
    ...
  },
  {
    "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:

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:

{
  "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 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:

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:

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:

[
  {
    ...
  },
  {
    "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:

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:

{
  "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:

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 and its creation timestamp:

[
{"token_id":828705046,"created_at":"2021-08-12T15:22:12Z"},        /* New token ID */
{"token_id":828704779,"created_at":"2021-08-12T15:20:03Z"}         /* 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:

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:

{
  "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:

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:

[
  828705046
]