Skip to main content

Authorization

Follow this guide to create a new Buildkite credential that will allow Nexla to authenticate to and exchange data with your Buildkite account.
buildkite_api_auth.png

Buildkite

Prerequisites​

To connect Nexla to Buildkite, you need a Buildkite API access token with the appropriate permissions for the operations you intend to perform. Buildkite API access tokens are user-scoped personal tokens that authenticate REST API requests using Bearer token authentication.

Generate a Buildkite API Access Token​

Buildkite API access tokens control access to your organization's data and pipelines. Tokens can be scoped to specific permissions (read, write, delete) for each Buildkite platform feature, ensuring that Nexla receives only the access it requires.

  1. Sign in to your Buildkite account at buildkite.com.

  2. Select your user profile icon in the top-right corner of the page, then select Personal Settings from the dropdown menu.

  3. In the Personal Settings navigation, select API Access Tokens.

  4. On the API Access Tokens page, select New API Access Token to open the token creation form.

  5. Enter a descriptive name in the Description field to identify this token's purpose — for example, Nexla Integration.

  6. Under Organization Access, select the specific Buildkite organization that Nexla should access. A token can be scoped to one or more organizations.

  7. Set a Token Expiry duration appropriate to your organization's security policies. Buildkite recommends rotating tokens at least once a year following OWASP best practices.

  8. Under REST API Scopes, select the permissions required for your intended Nexla use case:

    • For data source (reading data): Enable read permissions for Builds, Pipelines, Organizations, Jobs, Artifacts, and Agents as needed.

    • For destination (writing data): Enable read and write permissions for Builds and Pipelines to allow Nexla to trigger builds and create pipeline resources.

    • Recommended minimum for most integrations: Read permissions on Builds, Pipelines, and Organizations cover the majority of data ingestion use cases.

    You can use the Presets feature in the token creation form to quickly select all Read Only, all Read + Write, or all Full Access (including delete) permissions. For most Nexla integrations, Read Only or Read + Write presets are appropriate. Full Access (which includes delete permissions) should be granted only when required.

  9. Select Create New API Access Token. Enter your Buildkite password again if prompted.

  10. On the confirmation page, copy your new API access token immediately — this is the only time Buildkite will display the token value.

Important

Copy and securely store your API access token before leaving the confirmation page. Buildkite does not display the token value again after this page. If the token is lost, you must revoke it and generate a new one.

For complete information about Buildkite API access token scopes and permissions, see the Buildkite Managing API Access Tokens documentation.

Create a Buildkite Credential​

  • To create a new Buildkite credential, after selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

Credential Name & Description​

  1. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

    Resource descriptions are recommended but are not required. They should be used provide information about the resource purpose, data freshness, etc. that can help the owner and other users efficiently understand and utilize the resource.

API Key​

  1. Enter your Buildkite API access token in the API Key field. This token authenticates all Nexla requests to the Buildkite REST API using Bearer token authentication. Nexla will include this token in the Authorization: Bearer header with each API call.

    Keep your API access token secure. Treat it as you would a password — do not share it or commit it to source control. You can revoke and regenerate tokens at any time from the Buildkite Personal Settings > API Access Tokens page.

Save the Credential​

  1. Once all of the relevant steps in the above sections have been completed, click the Save button at the bottom of the overlay to save the configured credential.

  2. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation and can be selected for use with a new data source or destination.