Skip to main content
Community Hub

OAuth clients

TL;DR

Use OAuth 2.0 Client Credentials flow for short-lived access tokens in machine-to-machine integrations

Your AI can read this via Docs MCPcurl -fsSL "https://docs.atlan.com/install-docs-mcp" | bashConnect

OAuth clients provide secure, programmatic authentication to Atlan using the OAuth 2.0 Client Credentials flow. Instead of issuing a long-lived token, an OAuth client (identified by a client ID and client secret) obtains short-lived access tokens on demand and presents them to Atlan APIs using the standard Authorization: Bearer header.

Prerequisites​

  • Admin access to create and manage OAuth clients.
  • A defined scope for the client:
    • Role/subrole to control which administrative and governance APIs it may call.
    • Personas to grant access to the required connections and assets (least-privilege).
  • Your tenant base URL (for example, https://<your-tenant>.atlan.com) to construct API requests.

Create OAuth client​

Create a client that can obtain short-lived access tokens for programmatic authentication.

  1. Open your tenant and click Admin from the left menu.

  2. Click API access, then open the OAuth tab.

  3. In the upper-right, click Generate new and select Generate OAuth Client.

  4. In Name, enter an identifier for the integration. For example:

    dbt-cloud-sync

  5. In Description, add concise context for future administrators.

    Service account for dbt Cloud → Atlan sync

  6. In Role, choose the base role, it controls which administrative/governance APIs the client can call.

  7. In Personas, select personas that grant access to the required connections and assets.

  8. Click Save to create the client.

  9. Copy the Client ID and Client Secret and store them securely (secret manager or vault).

One-time visibility

The client secret is displayed only once. If it's lost or exposed, regenerate the client secret. You don't need to delete and recreate the client.

Regenerate client secret​

Regenerate a client's secret to rotate credentials on a schedule, or when a secret is lost or may have been exposed. The client ID stays the same, and so do the client's role, personas and connection admin assignments. Integrations only need the new secret.

The current secret stops working immediately

As soon as you regenerate, the old secret can no longer obtain access tokens. Plan the change so you can update every integration that uses the client right away.

  1. Open your tenant and click Admin from the left menu.

  2. Click API access, then open the OAuth tab.

  3. Find the client and, in its row, click the Regenerate client secret icon.

  4. Read the confirmation and click Regenerate.

  5. Copy the new Client Secret and store it securely (secret manager or vault). Like the original, it's displayed only once.

  6. Update every integration that uses this client with the new secret.

You can also regenerate a secret through the API. Call this endpoint with an access token that has admin permissions:

POST https://<your-tenant>.atlan.com/api/service/oauth-clients/<client-id>/regenerate-secret
Authorization: Bearer <access_token>

The response contains the new secret. To prevent misuse, you can regenerate a client's secret at most 5 times in 10 minutes. Further requests return 429 Too Many Requests with a Retry-After header.

Use OAuth client​

To use an OAuth client, obtain a short-lived access token with the client credentials and present that token as a bearer credential in each request.

  1. Request a short-lived access token from your tenant’s token endpoint.

    Endpoint

    POST https://<your-instance-name>.atlan.com/api/service/oauth-clients/token

    Request (HTTP)

    Content-Type: application/json

    {
    "clientId": "<client-id>",
    "clientSecret": "<client-secret>"
    }

  2. Read access_token and expires_in from the response, then attach the token to each API request.

    Authorization: Bearer <access_token>

  3. Call the desired API endpoint under your tenant base URL using the bearer token. For example, to list available type definitions:

    GET https://<your-tenant>.atlan.com/api/meta/types

    Headers:

    Authorization: Bearer <access_token>
    Content-Type: application/json

  4. Refresh the token before the expires_in period ends or immediately after a 401 Unauthorized.

See also​