Skip to content
Last updated

Identity and Access Management

The Aritma IAM API lets you control who can do what across your Aritma resources. It provides fine-grained access control through a policy-based permission model, combined with tools for managing users, groups, clients, and external identity providers.

Introduction

The IAM API is a REST API that acts as the central control plane for access management across all Aritma products.

Key concepts

Subjects

A subject is anything that can be granted permissions. Subjects can be:

  • Users - human identities linked to an Aritma ID account
  • Clients - OIDC service clients used for machine-to-machine API access
  • Groups - named collections of users and/or clients that share the same policies

Actions and Roles

An action is a string specifying some permission. Actions form a natural hierarchy - granting a parent action also grants all child actions beneath it.

banking                      ← top-level namespace
  banking.manage             ← grants all banking actions (role)
    banking.consents.create  ← specific permission (action)
    banking.ais.read         ← specific permission (action)
    banking.pis.manage       ← grants all banking payment initiation actions (role)
      banking.pis.write      ← specific permission (action)
      banking.pis.read       ← specific permission (action)

A role is a named bundle of actions. Assigning a role to a subject is a shorthand for granting all the actions that role includes - instead of creating individual policies for each action, you assign a role and the permissions follow.

See the Actions Hierarchy page (coming soon) for the full live tree of available actions.

Tenant Roles

Tenant roles are OIDC roles tied to a subject within a tenant. Unlike IAM policies (which grant fine-grained access to specific resources), tenant roles are returned as claims in the subjects's OIDC token and represent their standing within the organization - for example TenantAdmin and tenant.subject.read.

These roles are used by Aritma services to make coarse-grained authorization decisions at the application level, and can be inspected by your own applications from the token claims.

Scopes

A scope is a URI that identifies a specific resource. Policies are always scoped to a resource, so the same subject can have different permissions on different resources.

/subscriptions/123/resource-groups/456

Similar to actions and roles, a sub scope will inherit from its parent scope.

Policies

A policy is the binding that grants a subject permission to perform an action on a scope. Every resource-based access decision in Aritma resolves to a set of policies.

subject: user-555
action:  banking.manage
scope:   /subscriptions/123/resource-groups/456

This policy grants that user (with id 555) full banking management rights on resources under resource group 456 within subscription 123.

Additionally, due to the inheritance of scopes, any subscope of this resource group will inherit the permissions of this policy.

See the Policies guide for how to create, delete, and query policies.

Note, the ids used in these examples are not representative of the ids used in the actual api.

Groups

A group is a named collection of subjects. Policies assigned to a group apply to all members of that group. This makes it easy to manage access for teams without configuring each member individually.

See the Groups guide for how to create and manage groups.

What you can do

CapabilityGuide
Invite users, assign rolesUser Management
Organize users into groupsGroups
Grant fine-grained permissionsPolicies
Verify domain ownership for direct user creationDomains
Configure single sign-on (SSO)SSO Setup
Sync users from an external directorySCIM Provisioning
Create service clients for API accessOIDC Clients

Authentication

The IAM API uses OAuth 2.0. Two grant types are supported depending on your use case.

Machine-to-machine (client_credentials)

Use this when a backend service or script needs to access the API without a human user. Exchange a client ID and secret for a token:

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=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=services.iam"

See OIDC Clients for how to create and manage service clients.

User-facing applications (Authorization Code + PKCE)

Use this when your application needs to act on behalf of a logged-in user. Redirect the user to the Aritma authorization endpoint:

GET https://id.dev.aritma.io/connect/authorize
  ?response_type=code
  &client_id=<your-client-id>
  &redirect_uri=<your-redirect-uri>
  &scope=openid profile services.iam
  &code_challenge=<code-challenge>
  &code_challenge_method=S256
  &state=<random-state>

After the user authenticates and consents, exchange the authorization code for tokens:

curl -X POST https://id.dev.aritma.io/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=$CLIENT_ID" \
  -d "code=$AUTHORIZATION_CODE" \
  -d "redirect_uri=$REDIRECT_URI" \
  -d "code_verifier=$CODE_VERIFIER"

Using a token

Include the returned access_token as a Bearer token in all IAM API requests:

Authorization: Bearer <access_token>
 
Next page