## Managing OAuth clients

URL: https://docs.atlan.com/product/capabilities/build-apps/sdks/python/access-control/how-tos/manage-oauth-clients

> Create and manage OAuth 2.0 clients in Atlan using the Python SDK — assign roles and personas to enable machine-to-machine authentication flows.

# OAuthClient: create and manage OAuth 2.0 clients

Use `OAuthClient` in the Atlan Python SDK to programmatically create and manage OAuth 2.0 clients.

[OAuth clients](https://docs.atlan.com/get-started/references/api-access/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

:::warning[Under construction]
This feature isn't yet available in the Java SDK.
:::

### Python

```python showLineNumbers title="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.

 :::warning[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.

 :::warning[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

:::warning[Under construction]
This feature isn't yet available in the Kotlin SDK.
:::

### Go

:::warning[Under construction]
This feature isn't yet available in the Go SDK.
:::

### Raw REST API

```json showLineNumbers title="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

:::warning[Under construction]
This feature isn't yet available in the Java SDK.
:::

### Python

```python showLineNumbers title="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.

 :::note[Iterating over results produces a [Generator](https://wiki.python.org/moin/Generators)]
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

:::warning[Under construction]
This feature isn't yet available in the Kotlin SDK.
:::

### Go

:::warning[Under construction]
This feature isn't yet available in the Go SDK.
:::

### Raw REST API

```json showLineNumbers title="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

:::warning[Under construction]
This feature isn't yet available in the Java SDK.
:::

### Python

```python showLineNumbers title="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

:::warning[Under construction]
This feature isn't yet available in the Kotlin SDK.
:::

### Go

:::warning[Under construction]
This feature isn't yet available in the Go SDK.
:::

### Raw REST API

```json showLineNumbers title="GET /api/service/oauth-clients/oauth-client-abc123def456"
// (1)
```

## Update OAuth client

You can update an OAuth client's description:

### Java

:::warning[Under construction]
This feature isn't yet available in the Java SDK.
:::

### Python

```python showLineNumbers title="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

:::warning[Under construction]
This feature isn't yet available in the Kotlin SDK.
:::

### Go

:::warning[Under construction]
This feature isn't yet available in the Go SDK.
:::

### Raw REST API

```json showLineNumbers title="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

:::warning[Under construction]
This feature isn't yet available in the Java SDK.
:::

### Python

```python showLineNumbers title="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.

 :::warning[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

:::warning[Under construction]
This feature isn't yet available in the Kotlin SDK.
:::

### Go

:::warning[Under construction]
This feature isn't yet available in the Go SDK.
:::

### Raw REST API

```json showLineNumbers title="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.

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

---