Skip to content
/
Create a Service Client
Last updated

Create a Service Client

A backend service — such as a scheduled job or ERP integration — needs to call Aritma APIs without a human user. You need to give it scoped, revocable credentials.

Approach: Create an OIDC client, add a secret, then grant it access via a policy.

Prerequisites

  • An access token with IAM admin permissions
  • A configured tenant
  • The scope URI for the resource you want the client to access

Step 1: Create the 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"
    ]
  }'

Use allowedGrantTypes: ["client_credentials"] and an empty redirectUris array for service accounts.

Step 2: Add 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"
  }'
Save the secret

Store the returned value immediately — it is only shown once and cannot be retrieved again.

Step 3: Get 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>'

Note the subjectId from the response — you will use it as the subject in the policy.

Step 4: Grant the client permissions

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"
  }'

Use the client's subjectId as the policy subject. The client can now exchange its credentials for an access token and call the API within the granted scope.

Rotate credentials without downtime

When you need to rotate the secret, add a new secret first, update your service to use it, verify it works, then delete the old one. This ensures the service is never without valid credentials during the rotation.

See OIDC Clients for the full rotation procedure.

Next steps

Previous page
Next page