# 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](/apis/platform/iam/guides/policies) 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](/apis/platform/iam/guides/groups) for how to create and manage groups.

## What you can do

| Capability | Guide |
|  --- | --- |
| Invite users, assign roles | [User Management](/apis/platform/iam/guides/user-management) |
| Organize users into groups | [Groups](/apis/platform/iam/guides/groups) |
| Grant fine-grained permissions | [Policies](/apis/platform/iam/guides/policies) |
| Verify domain ownership for direct user creation | [Domains](/apis/platform/iam/guides/domains) |
| Configure single sign-on (SSO) | [SSO Setup](/apis/platform/iam/sso/overview) |
| Sync users from an external directory | [SCIM Provisioning](/apis/platform/iam/scim/overview) |
| Create service clients for API access | [OIDC Clients](/apis/platform/iam/clients/overview) |


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


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

See [OIDC Clients](/apis/platform/iam/clients/overview) 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:


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


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