• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
    No results for ""
    EXPAND ALL

    EDIT ON GITHUB

    API access tokens

    Read time: 5 minutes
    Last edited: Nov 18, 2022
    The REST API is a Pro and Enterprise feature

    The LaunchDarkly REST API is available to customers on a Pro or Enterprise plan. To learn more, read about our pricing. To upgrade your plan, contact Sales.

    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.

    API access tokens are private

    Only you have access the secret values of tokens you create. Other account members cannot access them. Administrators can delete your tokens, but cannot view their values.

    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.
    Never share an API access token

    API access tokens are secrets. If you share your access token with others, they may be able to use it to impersonate you, or perform actions with it that could later be attributed to you or your integration erroneously.

    You can also use the REST API: Access tokens

    Understanding access token permissions

    Personal API access tokens and the principle of least privilege

    As a best practice, we recommend giving your tokens the smallest scope required for your integration. For example, if your integration is not designed to modify your Production environment, use a custom role or inline policy to restrict access appropriately.

    Using custom roles in access tokens

    If you use custom roles to scope your access tokens, modifying the permissions of the custom roles will also modify the permissions of related tokens.

    There are two types of tokens you can create in LaunchDarkly. You can create a personal token, which is linked to an account member'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

    Service tokens are an Enterprise feature

    Service tokens are available to customers on an Enterprise plan. To learn more, read about our pricing. To upgrade your plan, contact Sales.

    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 you can never give a service token more permissions than you have.

    A service token's permissions are permanently fixed after you create it. You cannot edit the permissions of a service token, and 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, on the Authorization tab.

    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.

    Save new tokens immediately

    Your API access token is visible one time, immediately after you create it. If you leave or refresh the page where the token is displayed, it will be obscured and no longer visible. You must copy and store new access tokens somewhere secure before you leave the creation page, or you will lose access to the token.

    Here is a screenshot of the "Access tokens" section of the Authorization tab:

    The "Access tokens" section of the "Authorization" tab, with an obscured access token called out.
    The "Access tokens" section of the "Authorization" tab, with an obscured access token called out.

    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" panel appears:
    The "Access tokens" section with the "Create token" button called out.
    The "Access tokens" section with the "Create token" button called out.
    1. Give your token a human-readable Name.
    2. Assign a Role to the token by choosing one from the menu.
    3. Select the API version to assign to your token. By default, API requests you send using this token will use this API version. To learn more, read Versioning.
    4. (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:

    The "Create an access token" panel with the service token checkbox called out.
    The "Create an access token" panel with the service token checkbox called out.

    1. Click Save token. The new token appears in the Authorization page.
    2. Copy and save the token somewhere secure. After you leave this page, the token is obscured:
    A new access token with a reminder to copy and store it displayed.
    A new access token with a reminder to copy and store it displayed.

    You can also use the REST API: Create access token

    After you create a token, you can clone or delete it. You can also manage existing tokens from the Authorizations tab. You can reset the secret values of your tokens, or adjust the scope of your personal tokens.

    Cloning and deleting access tokens

    To clone or delete an access token:

    1. Navigate to the Account settings page.
    2. Click into the Authorization tab.
    3. Find your token in the "Access tokens" section.
    4. Click the overflow menu for the token and select from the menu:
    • "Clone token": 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" panel.
    • "Delete token": 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 clone and delete options:

    A new access token with the "Clone token" and "Delete token" options called out.
    A new access token with the "Clone token" and "Delete token" options called out.

    You can also use the REST API: Delete access token

    Resetting access tokens

    To reset your access token:

    1. Navigate to the Account settings page.
    2. Click into the Authorization tab.
    3. Find your token in the "Access tokens" section.
    4. Click the overflow menu for the token and select "Reset token" from the menu. The "Reset token" panel appears.
    5. Click Reset Token.
    6. In the "Reset token?" dialog, enter the number of hours to keep the old token active.
    7. Enter the name of the access token to confirm the reset. Then click Reset.

    Resetting a token invalidates it. You must copy and store the new token somewhere secure. Then, update any clients to use the new token.

    Rotate your tokens regularly

    As a best practice, we recommend rotating your tokens regularly to prevent tokens from becoming outdated, such as when account members leave. If you remove an account member from your account, their personal API access tokens become invalid. We recommend updating integrations to use new access tokens before removing account members.

    You can also use the REST API: Reset access token

    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 a Reader role can only create tokens with a Reader role, whereas account members with an Admin or Owner role 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.