> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/key-concepts/api-tokens.md). # API tokens API tokens let external clients authenticate requests to DataOS APIs. Every token is issued to a specific DataOS user (or service account), and it can only do what that user is permitted to do. A token is a credential, not a separate identity with its own permissions. ## Configuration API tokens can be created and managed from the **API Tokens** panel in DataOS Home, or from the DataOS CLI (`dataos-ctl`). ### Creating a new API token {% tabs %} {% tab title="API Tokens panel" %} 1. Open **Home** in DataOS. From the profile menu in the top-right corner, select **API Tokens**.
2. Select **+ New**, give the token a name you'll recognize later, and set an expiry (in hours or as a date) so it doesn't outlive its purpose.
3. Select **Save**, then copy the token value immediately. It's shown only once.
{% endtab %} {% tab title="CLI" %} ```bash dataos-ctl user apikey create --name ${{apikey-name}} [--duration ${{duration}}] ``` For example: ```bash dataos-ctl user apikey create --name ci-pipeline --duration 24h ``` The command prints the token value once, along with its type, expiration, creation time, and name. See [`dataos-ctl user apikey create`](/references/interfaces/command-line-interface/user.md#dataos-ctl-user-apikey-create) for the full flag reference. {% endtab %} {% endtabs %} {% hint style="warning" %} The token value is shown only once, at creation. Store it securely. It can't be viewed again later, from either the panel or the CLI. {% endhint %} ### Deleting an API token {% tabs %} {% tab title="API Tokens panel" %} Open the **API Tokens** panel, locate the token in the list, and select the delete/revoke action next to it. This immediately revokes access for anything using that token.
{% endtab %} {% tab title="CLI" %} ```bash dataos-ctl user apikey delete --name ${{apikey-name}} ``` See [`dataos-ctl user apikey delete`](/references/interfaces/command-line-interface/user.md#dataos-ctl-user-apikey-delete) for details. {% endtab %} {% endtabs %} ## Token expiry and rotation Every API token has an expiry, set at creation time (as a duration, such as `24h`, via `--duration` on the CLI, or as hours/a date in the panel). Once a token expires, it stops authenticating requests. Because a token's value can't be retrieved or edited after creation, rotation means creating a new token and replacing the old one wherever it's used, not renewing or extending the existing one. Set expiry to match how long the token is actually needed, and rotate it before it expires so dependent integrations don't fail unexpectedly. ## Usage Pass the token in the `Authorization` header of each API request: ``` Authorization: Bearer ``` This applies to REST APIs, and to any BI tool, SQL client, or AI client connecting to DataOS. Some accept the token as a bearer token or API-token field, while others (such as MySQL-protocol clients) use it as the connection password. ## Scope A token inherits the permissions of the DataOS user or service account it belongs to. Nothing more. DataOS applies that user's existing access (roles, product permissions, masking, and row filters) to every request made with the token, exactly as if the user made the request directly. If the underlying user lacks permission for a resource, requests made with the token are rejected with a `403 Forbidden`, the same as they would be for the user. A token is valid across every service and interface within the DataOS instance it was created in — REST APIs, the CLI, BI tools, SQL clients, and AI/MCP clients all authenticate with the same token, rather than each needing a separately scoped credential. It applies the creating user's permissions identically wherever it's used. A token is also tied to the instance it was created in: it won't authenticate against a different DataOS instance, even for the same user. This scoping also governs who can create a token in the first place: by default, a user can only create tokens for themselves. Creating one on behalf of another user is a separate, elevated permission — without it, the request is denied with a `403 Forbidden`. ## Features API tokens have the following features: * They can be used to authenticate API calls. * They have limited permissions (scopes), specified to user identity. * They are intended to be reusable. ## Limitations API tokens have the following limitations: * They can't be viewed or edited after they are created. They are intended to be replaced with a new API token rather than recovered or modified. * They can't be used to log in to DataOS instance. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://v2.dataos.info/references/key-concepts/api-tokens.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.