OIDC Clients
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

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

curl -i -X GET \
  'https://developer.aritma.com/_mock/apis/platform/iam/openapi/iam-openapi/v1/clients?searchText=string&page=0&pageSize=0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Create a client

curl -i -X POST \
  https://developer.aritma.com/_mock/apis/platform/iam/openapi/iam-openapi/v1/clients \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "My Application",
    "description": "string",
    "allowedGrantTypes": [
      "string"
    ],
    "redirectUris": [
      "string"
    ],
    "allowedScopes": [
      "string"
    ]
  }'

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
`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:

curl -i -X GET \
  'https://developer.aritma.com/_mock/apis/platform/iam/openapi/iam-openapi/v1/clients/{clientId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

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

curl -i -X GET \
  'https://developer.aritma.com/_mock/apis/platform/iam/openapi/iam-openapi/v1/clients/{clientId}/secrets?page=0&pageSize=0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Create a secret

curl -i -X POST \
  'https://developer.aritma.com/_mock/apis/platform/iam/openapi/iam-openapi/v1/clients/{clientId}/secrets' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "value": "s3cr3tV@lue!",
    "description": "Production API access",
    "expiration": "2019-08-24T14:15:22Z"
  }'

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

curl -i -X DELETE \
  'https://developer.aritma.com/_mock/apis/platform/iam/openapi/iam-openapi/v1/clients/{clientId}/secrets/{clientSecretId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Get an access token

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

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:

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

Use the access_token as a Bearer token in API calls:

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 to grant a client access to specific resources. First, find the client's subject ID:

curl -i -X GET \
  'https://developer.aritma.com/_mock/apis/platform/iam/openapi/iam-openapi/v1/subjects/clients?searchQuery=john&page=1&pageSize=100' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Then create a policy targeting that subject ID:

curl -i -X POST \
  https://developer.aritma.com/_mock/apis/platform/iam/openapi/iam-openapi/v1/policies \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "subject": "user-00000000-0000-0000-0000-000000000000",
    "scope": "/subscriptions/123",
    "action": "iam.policy.read"
  }'

To view the effective permissions already assigned to a client:

curl -i -X GET \
  'https://developer.aritma.com/_mock/apis/platform/iam/openapi/iam-openapi/v1/subjects/clients/{clientId}/permissions?resourceType=subscriptions&resourceProvider=aritma.control&action=iam.policy.read' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Update a client

curl -i -X PUT \
  'https://developer.aritma.com/_mock/apis/platform/iam/openapi/iam-openapi/v1/clients/{clientId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "My Application",
    "description": "string",
    "allowedGrantTypes": [
      "string"
    ],
    "redirectUris": [
      "string"
    ],
    "allowedScopes": [
      "string"
    ]
  }'

Delete a client

curl -i -X DELETE \
  'https://developer.aritma.com/_mock/apis/platform/iam/openapi/iam-openapi/v1/clients/{clientId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

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:

Create a new secret on the client
Update your service to use the new secret
Verify your service is working with the new secret
Delete the old secret

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

OIDC ClientsCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude