OAuth clients

OAuth clients provide an OAuth 2.0-based way to authenticate programmatic access to Atlan.

Create OAuth client

To create a new OAuth client, provide a name and role. Optionally, associate it with personas using their qualified names:

Java

Under construction

This feature isn't yet available in the Java SDK.

Python

Create an OAuth client

from pyatlan.client.atlan import AtlanClient

client = AtlanClient()

# First, retrieve the persona qualified name if you want to associate personas
personas = client.asset.find_personas_by_name("Data Assets")  # (1)
persona_qn = personas[0].qualified_name  # (2)

# Create the OAuth client
response = client.oauth_client.create(  # (3)
    name="dbt-cloud-integration",  # (4)
    role="Admin",  # (5)
    description="OAuth client for dbt Cloud integration",  # (6)
    persona_qualified_names=[persona_qn],  # (7)
)

# Access the response details
client_id = response.client_id  # (8)
client_secret = response.client_secret  # (9)
display_name = response.display_name  # (10)
created_by = response.created_by  # (11)
created_at = response.created_at  # (12)

print(f"OAuth Client ID: {client_id}")
print(f"OAuth Client Secret: {client_secret}")
print(f"Display Name: {display_name}")

1. Use asset.find_personas_by_name() to retrieve the persona you want to associate with the OAuth client. This returns a list of personas matching the given name.

2. Extract the qualified_name from the first matching persona. This is the personaQN that can be used to link the OAuth client to the persona.

3. Use the oauth_client.create() method to create a new OAuth client.

4. You must provide a unique name for the OAuth client.

5. You must provide a role for the OAuth client. This determines the permissions the OAuth client will have. Common roles include Admin, Member, and Guest—these correspond to the roles you see in the Atlan UI.

   Invalid role will raise an error

If you provide an invalid role, a NotFoundError will be raised with a message showing the available roles. ::: 6. Optionally provide a description for the OAuth client. 7. Optionally provide a list of persona qualified names to associate with the OAuth client. This grants the OAuth client the permissions defined in those personas. 8. The client_id is the unique identifier for the OAuth client. It will be prefixed with oauth-client-. 9. The client_secret is only available in this immediate response after creation.

Can't be accessed again later

You won't be able to retrieve the client secret again at a later point. Make sure to securely store it immediately after creation.

10. The display_name is the name you provided when creating the OAuth client.
11. The created_by indicates which user created the OAuth client.
12. The created_at is the timestamp when the OAuth client was created.

Kotlin

Under construction

This feature isn't yet available in the Kotlin SDK.

Go

Under construction

This feature isn't yet available in the Go SDK.

Raw REST API

POST /api/service/oauth-clients

{
  "displayName": "dbt-cloud-integration", // (1)
  "description": "OAuth client for dbt Cloud integration", // (2)
  "roles": "$member", // (3)
  "personaQNs": ["default/aQi5KHtGwZYvxGnTSAYO8J"] // (4)
}

1. You must provide a unique name for the OAuth client.
2. Optionally provide a description for the OAuth client.
3. You must provide a role to the OAuth client. Common roles include $admin, $member, and $guest.
4. Optionally provide a list of persona qualified names to associate with the OAuth client.

Retrieve OAuth clients

You can retrieve OAuth clients with pagination support and iterate through them:

Java

Under construction

This feature isn't yet available in the Java SDK.

Python

Retrieve OAuth clients with pagination

from pyatlan.client.atlan import AtlanClient

client = AtlanClient()

response = client.oauth_client.get(  # (1)
    limit=10,  # (2)
    offset=0,  # (3)
    sort="-createdAt",  # (4)
)

print(f"Total OAuth clients: {response.total_record}")  # (5)

for oauth_client in response:  # (6)
    print(f"Name: {oauth_client.display_name}")
    print(f"Client ID: {oauth_client.client_id}")
    print(f"Description: {oauth_client.description}")

1. Use the oauth_client.get() method to retrieve OAuth clients with pagination.

2. (Optional) The limit parameter specifies the maximum number of results to return. Defaults to 20.

3. (Optional) The offset parameter specifies the starting position for pagination. Defaults to 0.

4. (Optional) The sort parameter specifies the field to sort results by. Use - prefix for descending order (for example, -createdAt for newest first).

5. The total_record property contains the total count of OAuth clients.

6. You can iterate directly over the response object. This will lazily load and loop through each page of results until the loop finishes or you break out of it.

   Iterating over results produces a Generator

This means that results are retrieved from the backend a page at a time. This also means that you can only iterate over the results once. :::

Kotlin

Under construction

This feature isn't yet available in the Kotlin SDK.

Go

Under construction

This feature isn't yet available in the Go SDK.

Raw REST API

GET /api/service/oauth-clients?limit=20&offset=0&sort=-createdAt&count=true

// (1)

1. The pagination and sorting parameters are passed as query parameters in the URL.

Retrieve OAuth client by ID

You can retrieve an OAuth client by its unique client ID:

Java

Under construction

This feature isn't yet available in the Java SDK.

Python

Retrieve an OAuth client by ID

from pyatlan.client.atlan import AtlanClient

client = AtlanClient()

oauth_client = client.oauth_client.get_by_id(  # (1)
    "oauth-client-abc123def456"
)

print(f"ID: {oauth_client.id}")
print(f"Client ID: {oauth_client.client_id}")
print(f"Name: {oauth_client.display_name}")
print(f"Description: {oauth_client.description}")

1. The oauth_client.get_by_id() method retrieves an OAuth client by its unique client ID. The client ID is prefixed with oauth-client-.

Kotlin

Under construction

This feature isn't yet available in the Kotlin SDK.

Go

Under construction

This feature isn't yet available in the Go SDK.

Raw REST API

GET /api/service/oauth-clients/oauth-client-abc123def456

// (1)

Update OAuth client

You can update an OAuth client's description:

Java

Under construction

This feature isn't yet available in the Java SDK.

Python

Update an OAuth client

from pyatlan.client.atlan import AtlanClient

client = AtlanClient()

# First retrieve the OAuth client you want to update
oauth_client = client.oauth_client.get_by_id(  # (1)
    "oauth-client-abc123def456"
)

# Update the OAuth client's description
updated_client = client.oauth_client.update(  # (2)
    client_id=oauth_client.client_id,  # (3)
    description="Updated description for dbt Cloud integration",  # (4)
)

print(f"Updated description: {updated_client.description}")

1. First retrieve the OAuth client you want to update to get its client ID.
2. Use the oauth_client.update() method to update the OAuth client.
3. You must provide the client_id of the OAuth client to update.
4. Provide the new description for the OAuth client.

Kotlin

Under construction

This feature isn't yet available in the Kotlin SDK.

Go

Under construction

This feature isn't yet available in the Go SDK.

Raw REST API

PUT /api/service/oauth-clients/oauth-client-abc123def456

{ // (1)
  "description": "Updated description for dbt Cloud integration",  // (2)
  "name": "new-name" // (3)
} 

1. The client ID is passed as a path parameter in the URL.
2. Provide the updated description in the request body.
3. Provide the updated name in the request body.

Delete OAuth client

To permanently delete an OAuth client, use the purge() method:

Java

Under construction

This feature isn't yet available in the Java SDK.

Python

Delete an OAuth client

from pyatlan.client.atlan import AtlanClient

client = AtlanClient()

# Purge the OAuth client by its client ID
client.oauth_client.purge("oauth-client-abc123def456")  # (1)

1. Use the oauth_client.purge() method with the client ID to permanently delete the OAuth client.

   Irreversible

Once deleted, the OAuth client will be permanently removed and can no longer be used for authentication. Any systems using this OAuth client's credentials will immediately lose access. :::

Kotlin

Under construction

This feature isn't yet available in the Kotlin SDK.

Go

Under construction

This feature isn't yet available in the Go SDK.

Raw REST API

DELETE /api/service/oauth-clients/oauth-client-abc123def456

// (1)

1. The client ID is passed as a path parameter in the URL. No request body is required.

   Irreversible

Once deleted, the OAuth client will be permanently removed and can no longer be used for authentication. :::