API access tokens

Overview

This topic explains how to use API access tokens to authenticate with the LaunchDarkly REST API, as well as constraints and suggestions for implementing them.

Scoping personal API access tokens

You can scope your API tokens to restrict the set of operations they can perform. For example, you can build an integration that only has read access to the REST API.

The available scoping options are:

• Built-in roles: Gives a token the same permissions as a reader, writer, or admin.
• Custom roles: Gives a token the same permissions as one of your team's existing custom roles. This option is only available if your LaunchDarkly plan includes custom roles.
• In-line custom roles: Gives a token a custom set of permissions in-line, rather than specifying it as an existing custom role. This option is only available if your LaunchDarkly plan includes custom roles.

Understanding access token permissions

There are two types of tokens you can create in LaunchDarkly. You can create a personal token, which is linked to a user's account, or a service token, which is independent of the account that created it.

The different token types respond differently when their creators' permissions change. Because of this, you may want to use different types of tokens for different things.

Personal tokens

You can configure a personal access token to have the same permissions that you do, or more restrictive permissions. Your personal tokens can never do more than you can in LaunchDarkly.

If your own permissions are ever reduced, personal tokens you have created have reduced scope as well. For example, if you are a Writer and create a Writer token, but then are downgraded to a Reader, your Writer token is also downgraded. After your permissions change, that token behaves like a Reader token.

If an account member with personal access tokens is removed from your LaunchDarkly team, their personal tokens are deactivated.

Use a personal token when you want to access the LaunchDarkly API for your temporary or personal use.

Service tokens

Unlike personal tokens, service tokens are not tied to your LaunchDarkly profile. You can assign an existing role to a service token, or create a custom role for it to use, but like personal access tokens, you can never give a service token more permissions than you have.

You can also configure service tokens to have up to the same permissions you do, but those permissions are fixed. Even if your permissions change, the service token's permissions stay the same.

Use a service token to create long-term integrations with the LaunchDarkly API.

Creating API access tokens

You can create an API access token from the Account settings page.

By default, the tokens you create on the Account settings page are personal tokens. You can choose to create a service token instead during the token creation workflow.

Here is a screenshot of the Access tokens page:

To create an access token:

1. Navigate to the Account settings page.
2. Click into the Authorization tab.
3. Click Create token. The Create an access token screen appears:

4. Give your token a human-readable Name.
5. Assign a Role to the token by choosing one from the dropdown.
6. (Optional) Select the "This is a service token" checkbox if you wish to create a service token. This feature is only available to customers on Enterprise plans:

7. Click Save Token. The new token appears in the Authorization page.
8. Copy and save the token somewhere secure. After you leave this page, the token is obscured:

After you create a token, you can Clone or Delete it from the "Access tokens" screen.

• Clone: Clones the access token. This allows you to create multiple access tokens with the same set of permissions, rather than having to fill out each token's information in the "Create an access token" screen.
• Delete: Deletes the access token. If you delete a token, API calls made with that token return 401 Unauthorized status codes.

Here is a screenshot of the access tokens screen:

You can also manage existing tokens from the Authorizations tab. From that tab, you can reset the secret values of your tokens, or delete them. You may also adjust the scope of your personal tokens.

Restricting who can create and manage API access tokens

By default, all account members can create access tokens limited to their existing permissions. Account members with reader level permissions can only create tokens with reader permissions, whereas admins and owners can create tokens with any permission level.

You can restrict account members from creating or managing access tokens with custom roles.

To learn more, read Actions in custom roles.