OAuth clients

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

Create an OAuth client

8.4.6

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

Java Python Kotlin Go Raw REST API

Under construction

This feature is not yet available in the Java SDK.

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.

   Cannot be accessed again later

   You will not 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.

Under construction

This feature is not yet available in the Kotlin SDK.

Under construction

This feature is not yet available in the Go SDK.

{
  "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

8.4.6

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

Java Python Kotlin Go Raw REST API

Under construction

This feature is not yet available in the Java SDK.

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 (e.g., -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.

Under construction

This feature is not yet available in the Kotlin SDK.

Under construction

This feature is not yet available in the Go SDK.

// (1)

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

Retrieve an OAuth client by ID

8.4.6

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

Java Python Kotlin Go Raw REST API

Under construction

This feature is not yet available in the Java SDK.

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-.

Under construction

This feature is not yet available in the Kotlin SDK.

Under construction

This feature is not yet available in the Go SDK.

// (1)

Update an OAuth client

8.4.6

You can update an OAuth client's description:

Java Python Kotlin Go Raw REST API

Under construction

This feature is not yet available in the Java SDK.

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.

Under construction

This feature is not yet available in the Kotlin SDK.

Under construction

This feature is not yet available in the Go SDK.

{ // (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 an OAuth client

8.4.6

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

Java Python Kotlin Go Raw REST API

Under construction

This feature is not yet available in the Java SDK.

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.

Under construction

This feature is not yet available in the Kotlin SDK.

Under construction

This feature is not yet available in the Go SDK.

// (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.

---