{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-apis/platform/iam/sidebars.yaml","oas-apis/platform/iam/openapi/iam-openapi.json":"oas-apis/platform/iam/openapi/iam-openapi.json"},"props":{"metadata":{"markdoc":{"tagList":["openapi-code-sample","admonition"]},"type":"markdown"},"seo":{"title":"OIDC Clients","keywords":"documentation, api, portal, banking, payment, account information, aritma, psd2, open banking, reconciliation","description":"Developer documentation for Aritma's banking and financial APIs - payments, account information, webhooks, authentication and integrations.","meta":[{"name":"google-site-verification","content":"hplqlK_5O42BZjNnjtVQMEpxv9JkxcD1eH4J1T-NQmI"}],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"oidc-clients","__idx":0},"children":["OIDC Clients"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Clients use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_credentials"]}," grant type: they exchange a client ID and secret for an access token, which is then used to call APIs."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"when-to-use-clients","__idx":1},"children":["When to use clients"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A backend service needs to call the Aritma Banking or Events API"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An ERP integration runs scheduled jobs that access Aritma resources"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A CI/CD pipeline needs API access as part of an automated workflow"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Clients are treated as subjects in the IAM system - you can assign policies directly to a client, granting it specific permissions on specific scopes."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"list-clients","__idx":2},"children":["List clients"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/platform/iam/openapi/iam-openapi.json","operationId":"GetClients","language":"curl","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-a-client","__idx":3},"children":["Create a client"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/platform/iam/openapi/iam-openapi.json","operationId":"CreateClient","language":"curl","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The display name of the client"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A human-readable description"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedGrantTypes"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The OAuth 2.0 grant types the client may use, e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_credentials"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authorization_code"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["allowedScopes"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The scopes the client is allowed to request. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/platform/iam/openapi/iam-openapi#tag/Scope"},"children":["available scopes"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redirectUris"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The allowed redirect URIs for authorization code flows. Use an empty array for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_credentials"]},"-only clients"]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"get-a-client","__idx":4},"children":["Get a client"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retrieve a client by its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientId"]},":"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/platform/iam/openapi/iam-openapi.json","operationId":"GetClientByClientId","language":"curl","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"manage-client-secrets","__idx":5},"children":["Manage client secrets"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Secrets are used along with the client ID to obtain access tokens. A client can have multiple secrets - useful when rotating credentials without downtime."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"list-secrets","__idx":6},"children":["List secrets"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/platform/iam/openapi/iam-openapi.json","operationId":"GetClientSecrets","language":"curl","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-a-secret","__idx":7},"children":["Create a secret"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/platform/iam/openapi/iam-openapi.json","operationId":"CreateClientSecret","language":"curl","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The secret value. Must be between 8 and 32 characters"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A human-readable description of what this secret is used for"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiration"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional expiration date (ISO 8601). If omitted, the secret does not expire"]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Save your secret"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"delete-a-secret","__idx":8},"children":["Delete a secret"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/platform/iam/openapi/iam-openapi.json","operationId":"DeleteClientsecret","language":"curl","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"get-an-access-token","__idx":9},"children":["Get an access token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once you have a client ID and secret, exchange them for an access token using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_credentials"]}," grant:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://id.dev.aritma.io/connect/token\" \\\n  -H \"Content-Type: application/x-www-form-urlencoded\" \\\n  -d \"grant_type=client_credentials\" \\\n  -d \"client_id=my-backend-service\" \\\n  -d \"client_secret=abc123xyz...\" \\\n  -d \"scope=api\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"access_token\": \"<jwt>\",\n  \"expires_in\": 3600,\n  \"token_type\": \"Bearer\",\n  \"scope\": \"api\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_token"]}," as a Bearer token in API calls:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"Authorization: Bearer <access_token>\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Tokens expire after ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_in"]}," seconds (typically 1 hour). Request a new token before or after the current one expires."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"grant-a-client-permissions","__idx":10},"children":["Grant a client permissions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Clients are subjects in IAM. Use ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/platform/iam/guides/policies"},"children":["Policies"]}," to grant a client access to specific resources. First, find the client's subject ID:"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/platform/iam/openapi/iam-openapi.json","operationId":"GetClientSubjects","language":"curl","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Then create a policy targeting that subject ID:"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/platform/iam/openapi/iam-openapi.json","operationId":"CreatePolicy","language":"curl","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To view the effective permissions already assigned to a client:"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/platform/iam/openapi/iam-openapi.json","operationId":"GetClientPermissions","language":"curl","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"update-a-client","__idx":11},"children":["Update a client"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/platform/iam/openapi/iam-openapi.json","operationId":"UpdateClient","language":"curl","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"delete-a-client","__idx":12},"children":["Delete a client"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/platform/iam/openapi/iam-openapi.json","operationId":"DeleteClient","language":"curl","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Deleting a client also deletes all its secrets and policies. Any running services using this client will immediately lose API access."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"secret-rotation","__idx":13},"children":["Secret rotation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To rotate a client secret without downtime:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a new secret on the client"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update your service to use the new secret"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify your service is working with the new secret"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Delete the old secret"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This ensures there is no gap in API access during the rotation."]}]},"headings":[{"value":"OIDC Clients","id":"oidc-clients","depth":1},{"value":"When to use clients","id":"when-to-use-clients","depth":2},{"value":"List clients","id":"list-clients","depth":2},{"value":"Create a client","id":"create-a-client","depth":2},{"value":"Get a client","id":"get-a-client","depth":2},{"value":"Manage client secrets","id":"manage-client-secrets","depth":2},{"value":"List secrets","id":"list-secrets","depth":3},{"value":"Create a secret","id":"create-a-secret","depth":3},{"value":"Delete a secret","id":"delete-a-secret","depth":3},{"value":"Get an access token","id":"get-an-access-token","depth":2},{"value":"Grant a client permissions","id":"grant-a-client-permissions","depth":2},{"value":"Update a client","id":"update-a-client","depth":2},{"value":"Delete a client","id":"delete-a-client","depth":2},{"value":"Secret rotation","id":"secret-rotation","depth":2}],"frontmatter":{"title":"OIDC Clients","seo":{"title":"OIDC Clients"}},"lastModified":"2026-05-08T13:38:07.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/platform/iam/clients/overview","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}