# OIDC Clients

A **client** in Aritma IAM is an OAuth 2.0 / OpenID Connect client - used by applications, services, or scripts that need to authenticate against Aritma APIs without a human user.

Clients use the `client_credentials` grant type: they exchange a client ID and secret for an access token, which is then used to call APIs.

## When to use clients

- A backend service needs to call the Aritma Banking or Events API
- An ERP integration runs scheduled jobs that access Aritma resources
- A CI/CD pipeline needs API access as part of an automated workflow


Clients are treated as subjects in the IAM system - you can assign policies directly to a client, granting it specific permissions on specific scopes.

## List clients

## Create a client

| Field | Required | Description |
|  --- | --- | --- |
| `name` | Yes | The display name of the client |
| `description` | Yes | A human-readable description |
| `allowedGrantTypes` | Yes | The OAuth 2.0 grant types the client may use, e.g. `client_credentials`, `authorization_code` |
| `allowedScopes` | Yes | The scopes the client is allowed to request. See [available scopes](/apis/platform/iam/openapi/iam-openapi#tag/Scope) |
| `redirectUris` | Yes | The allowed redirect URIs for authorization code flows. Use an empty array for `client_credentials`-only clients |


Note
A newly created client has no secrets and no permissions. You must add a secret before it can authenticate, and create policies to grant it access to resources.

## Get a client

Retrieve a client by its `clientId`:

## Manage client secrets

Secrets are used along with the client ID to obtain access tokens. A client can have multiple secrets - useful when rotating credentials without downtime.

### List secrets

### Create a secret

| Field | Required | Description |
|  --- | --- | --- |
| `value` | Yes | The secret value. Must be between 8 and 32 characters |
| `description` | Yes | A human-readable description of what this secret is used for |
| `expiration` | No | Optional expiration date (ISO 8601). If omitted, the secret does not expire |


Save your secret
The `value` is only returned once at creation time. Store it securely - it cannot be retrieved later. If lost, delete the secret and create a new one.

### Delete a secret

## Get an access token

Once you have a client ID and secret, exchange them for an access token using the `client_credentials` grant:


```bash
curl -X POST "https://id.dev.aritma.io/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=my-backend-service" \
  -d "client_secret=abc123xyz..." \
  -d "scope=api"
```

**Response:**


```json
{
  "access_token": "<jwt>",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "api"
}
```

Use the `access_token` as a Bearer token in API calls:


```http
Authorization: Bearer <access_token>
```

Tokens expire after `expires_in` seconds (typically 1 hour). Request a new token before or after the current one expires.

## Grant a client permissions

Clients are subjects in IAM. Use [Policies](/apis/platform/iam/guides/policies) to grant a client access to specific resources. First, find the client's subject ID:

Then create a policy targeting that subject ID:

To view the effective permissions already assigned to a client:

## Update a client

## Delete a client

Warning
Deleting a client also deletes all its secrets and policies. Any running services using this client will immediately lose API access.

## Secret rotation

To rotate a client secret without downtime:

1. Create a new secret on the client
2. Update your service to use the new secret
3. Verify your service is working with the new secret
4. Delete the old secret


This ensures there is no gap in API access during the rotation.