API docs by Redocly

IAM API (1.0.0)

Download OpenAPI specification:

Authentication, users, roles, and tenants.

API Keys

List API keys

List API keys with pagination and filters

Authorizations:
BearerAuth
query Parameters
search
string

Search term (name or key_prefix)

status
Array of strings

Status filter (active, revoked, expired)

service_account_id
string

Filter by service account ID

page
integer
Default: 1

Page number

page_size
integer
Default: 10

Page size

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Create an API key

Create a new API key for a service account. The raw key is returned once.

Authorizations:
BearerAuth
Request Body schema: application/json
required

API key creation request

description
string <= 500 characters
expires_at
string
name
required
string <= 255 characters
service_account_id
required
string

Responses

Request samples

Content type
application/json
{
  • "description": "API key used for ERP data synchronization",
  • "expires_at": "2025-12-31T23:59:59Z",
  • "name": "ERP Sync Key",
  • "service_account_id": "01J5C2D3E4F5G6H7I8J9K0L1M2"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Get an API key

Retrieve an API key by ID

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

API Key ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Delete an API key

Permanently delete an API key

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

API Key ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "message": "string",
  • "success": true
}

Update an API key

Update an API key's name or expiration

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

API Key ID

Request Body schema: application/json
required

Update request

description
string <= 500 characters
expires_at
string
name
string <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "description": "Updated description",
  • "expires_at": "2026-06-30T23:59:59Z",
  • "name": "Updated ERP Key"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Change API key status

Change an API key's status (e.g., revoke)

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

API Key ID

Request Body schema: application/json
required

Status change request

status
required
string
Enum: "active" "revoked"

Responses

Request samples

Content type
application/json
{
  • "status": "revoked"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Auth

Login

Authenticate user and issue JWT tokens with default or specified tenant

Request Body schema: application/json
required

Login credentials

client_id
required
string
email
required
string
password
required
string
tenant_id
string

Optional: specify tenant

Responses

Request samples

Content type
application/json
{
  • "client_id": "pim_web",
  • "email": "user@example.com",
  • "password": "SecurePass123!",
  • "tenant_id": "0193a5b6-e7c0-7df0-b4b1-c0a1f5e3a8d1"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Logout

Logout user and clear cached permissions

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "message": "string",
  • "success": true
}

Get current user info

Get current authenticated user information with roles, permissions, and tenants from Redis cache

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Change password

Change current user's password

Authorizations:
BearerAuth
Request Body schema: application/json
required

Password change request

new_password
required
string >= 8 characters
old_password
required
string >= 8 characters

Responses

Request samples

Content type
application/json
{
  • "new_password": "NewSecurePass456!",
  • "old_password": "OldPass123!"
}

Response samples

Content type
application/json
{
  • "data": null,
  • "success": true
}

Refresh access token

Get a new access token using refresh token

Request Body schema: application/json
required

Refresh token

client_id
required
string
refresh_token
required
string

Responses

Request samples

Content type
application/json
{
  • "client_id": "pim_web",
  • "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Switch to another accessible tenant

Switch the current user to another tenant they have access to without re-authentication

Authorizations:
BearerAuth
Request Body schema: application/json
required

Switch tenant request

client_id
required
string
tenant_id
required
string

Responses

Request samples

Content type
application/json
{
  • "client_id": "pim_web",
  • "tenant_id": "0193a5b6-e7c0-7df0-b4b1-c0a1f5e3a8d3"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Reset password (admin)

Reset a user's password (admin only)

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

User ID

Request Body schema: application/json
required

Password reset request

new_password
required
string >= 8 characters
user_id
required
string

Responses

Request samples

Content type
application/json
{
  • "new_password": "ResetPass789!",
  • "user_id": "0193a5b6-e7c0-7df0-b4b1-c0a1f5e3a8d2"
}

Response samples

Content type
application/json
{
  • "data": null,
  • "success": true
}

Features

List features

Get a paginated list of features

Authorizations:
BearerAuth
query Parameters
page
integer
Default: 1

Page number

page_size
integer
Default: 20

Page size

search
string

Search term

status
Array of strings

Filter by status

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Create a new feature

Create a new feature in the system

Authorizations:
BearerAuth
Request Body schema: application/json
required

Feature creation request

code
required
string

Responses

Request samples

Content type
application/json
{
  • "code": "product_management"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Get feature by ID

Get a feature by their ID

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Feature ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Delete feature

Soft delete a feature

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Feature ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "message": "string",
  • "success": true
}

Change feature status

Change the status of a feature (activate/deactivate)

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Feature ID

Request Body schema: application/json
required

Feature status change request

status
required
string
Enum: "active" "inactive"

Responses

Request samples

Content type
application/json
{
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Users

List users in an organization

List all users that belong to any tenant within the specified organization

Authorizations:
BearerAuth
path Parameters
org_id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Organization ID

query Parameters
page
integer
Default: 1

Page number

page_size
integer
Default: 20

Page size

search
string

Search term

status
Array of strings

Filter by status

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

List users in my tenant

Get a paginated list of users scoped to the caller's JWT tenant

Authorizations:
BearerAuth
query Parameters
page
integer
Default: 1

Page number

page_size
integer
Default: 20

Page size

search
string

Search term

status
Array of strings

Filter by status

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Create a user

Create a new user or assign an existing one to the caller's JWT tenant

Authorizations:
BearerAuth
Request Body schema: application/json
required

Create/assign user request

email
string <= 255 characters

New user fields (required when user_id is absent)

name
string [ 1 .. 255 ] characters
password
string [ 6 .. 100 ] characters
role_ids
Array of strings

Optional roles to assign (role IDs)

user_id
string

Existing user — mutually exclusive with Email/Name

Responses

Request samples

Content type
application/json
{
  • "email": "john@company.com",
  • "name": "John Doe",
  • "password": "string",
  • "role_ids": [
    ],
  • "user_id": "0193a5b6-e7c0-7df0-b4b1-c0a1f5e3a8d2"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Get user by ID

Get a user by their ID

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

User ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Delete a user

Remove a user from the caller's JWT tenant

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

User ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "message": "string",
  • "success": true
}

Update user

Update an existing user

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

User ID

Request Body schema: application/json
required

User update request

email
string <= 255 characters
name
string [ 1 .. 255 ] characters
role_ids
Array of strings

Already optional with pointer

Responses

Request samples

Content type
application/json
{
  • "email": "jane.smith@example.com",
  • "name": "Jane Smith",
  • "role_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Get user roles

Get all roles assigned to a user in the caller's JWT tenant

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

User ID

query Parameters
page
integer
Default: 1

Page number

page_size
integer
Default: 20

Page size

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Add roles to user

Add roles to a user in the caller's JWT tenant. Uses PATCH semantics — adds to existing roles without removing them.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

User ID

Request Body schema: application/json
required

Role IDs to add

role_ids
required
Array of strings non-empty

Responses

Request samples

Content type
application/json
{
  • "role_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": null,
  • "success": true
}

Remove a role from user

Remove a single role from a user in the caller's JWT tenant

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

User ID

role_id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M3

Role ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "message": "string",
  • "success": true
}

Change user status

Change a user's status (activate or deactivate)

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

User ID

Request Body schema: application/json
required

Status change request

status
required
string
Enum: "active" "inactive" "suspended"

Responses

Request samples

Content type
application/json
{
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Get user tenants

Get all tenants a user has access to

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

User ID

query Parameters
page
integer
Default: 1

Page number

page_size
integer
Default: 20

Page size

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Permissions

List permissions

List permissions with pagination and filters

Authorizations:
BearerAuth
query Parameters
feature_id
string

Feature ID filter

sub_feature_id
string

Sub-feature ID filter

search
string

Search term

status
Array of strings

Status filter

page
integer
Default: 1

Page number

page_size
integer
Default: 10

Page size

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Create a new permission

Create a new permission

Authorizations:
BearerAuth
Request Body schema: application/json
required

Permission creation request

code
required
string <= 100 characters

Responses

Request samples

Content type
application/json
{
  • "code": "iam:features:view"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Get a permission by ID

Get a permission by ID

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Permission ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Delete a permission

Soft delete a permission

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Permission ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "message": "string",
  • "success": true
}

Update a permission

Change a permission's status

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Permission ID

Request Body schema: application/json
required

Permission status change request

status
required
string
Enum: "active" "inactive"

Responses

Request samples

Content type
application/json
{
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Roles

List roles

List roles with pagination and filters

Authorizations:
BearerAuth
query Parameters
tenant_id
string

Tenant ID filter (must be in user's accessible tenants)

search
string

Search term

status
Array of strings

Status filter

page
integer
Default: 1

Page number

page_size
integer
Default: 10

Page size

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Create a new role

Create a new role

Authorizations:
BearerAuth
Request Body schema: application/json
required

Role creation request

code
required
string
description
string
name
required
string <= 255 characters
permission_ids
Array of strings

Responses

Request samples

Content type
application/json
{
  • "code": "admin",
  • "description": "Full system access",
  • "name": "Administrator",
  • "permission_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Get a role by ID

Get a role by ID

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Role ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Delete a role

Soft delete a role

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Role ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "message": "string",
  • "success": true
}

Update a role

Update a role

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Role ID

Request Body schema: application/json
required

Role update request

description
string
name
string

Responses

Request samples

Content type
application/json
{
  • "description": "Updated description",
  • "name": "Super Administrator"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Get role permissions

Get all permissions assigned to a role

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Role ID

query Parameters
page
integer
Default: 1

Page number

page_size
integer
Default: 20

Page size

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Remove a permission from role

Assign permissions to a role (adds to existing) Remove a single permission from a role

Authorizations:
BearerAuthBearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Role ID

id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Role ID

Request Body schema: application/json
required

Permissions to assign

permission_ids
required
Array of strings non-empty

Responses

Request samples

Content type
application/json
{
  • "permission_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": null,
  • "success": true
}

Remove a permission from role

Assign permissions to a role (adds to existing) Remove a single permission from a role

Authorizations:
BearerAuthBearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Role ID

id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Role ID

Request Body schema: application/json
required

Permissions to assign

permission_ids
required
Array of strings non-empty

Responses

Request samples

Content type
application/json
{
  • "permission_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": null,
  • "success": true
}

Remove a permission from role

Assign permissions to a role (adds to existing) Remove a single permission from a role

Authorizations:
BearerAuthBearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Role ID

id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Role ID

permission_id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Permission ID

Request Body schema: application/json
required

Permissions to assign

permission_ids
required
Array of strings non-empty

Responses

Request samples

Content type
application/json
{
  • "permission_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": null,
  • "success": true
}

Remove a permission from role

Assign permissions to a role (adds to existing) Remove a single permission from a role

Authorizations:
BearerAuthBearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Role ID

id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Role ID

permission_id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Permission ID

Request Body schema: application/json
required

Permissions to assign

permission_ids
required
Array of strings non-empty

Responses

Request samples

Content type
application/json
{
  • "permission_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": null,
  • "success": true
}

Change role status

Change a role's status (activate or deactivate)

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Role ID

Request Body schema: application/json
required

Status change request

status
required
string
Enum: "active" "inactive"

Responses

Request samples

Content type
application/json
{
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Service Accounts

List service accounts

List service accounts with pagination and filters

Authorizations:
BearerAuth
query Parameters
search
string

Search term (name or code)

status
Array of strings

Status filter (active, inactive)

page
integer
Default: 1

Page number

page_size
integer
Default: 10

Page size

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Create a service account

Create a new service account (machine identity)

Authorizations:
BearerAuth
Request Body schema: application/json
required

Service account creation request

code
required
string
description
string
name
required
string <= 255 characters
role_ids
Array of strings

Responses

Request samples

Content type
application/json
{
  • "code": "erp-connector",
  • "description": "Service account for ERP integration",
  • "name": "ERP Connector",
  • "role_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Get a service account

Retrieve a service account by ID

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Service Account ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Delete a service account

Delete a service account and its role mappings

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Service Account ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "message": "string",
  • "success": true
}

Update a service account

Update a service account's name or description

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Service Account ID

Request Body schema: application/json
required

Update request

description
string
name
string <= 255 characters
role_ids
Array of strings

Responses

Request samples

Content type
application/json
{
  • "description": "Updated description",
  • "name": "Updated ERP Connector",
  • "role_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Change service account status

Change a service account's status (activate or deactivate)

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Service Account ID

Request Body schema: application/json
required

Status change request

status
required
string
Enum: "active" "inactive"

Responses

Request samples

Content type
application/json
{
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Sub-Features

List sub-features

Get a paginated list of sub-features

Authorizations:
BearerAuth
query Parameters
feature_id
string

Filter by feature ID

page
integer
Default: 1

Page number

page_size
integer
Default: 20

Page size

search
string

Search term

status
Array of strings

Filter by status

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Create a new sub-feature

Create a new sub-feature in the system

Authorizations:
BearerAuth
Request Body schema: application/json
required

Sub-feature creation request

code
required
string

Responses

Request samples

Content type
application/json
{
  • "code": "product_catalog"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Get sub-feature by ID

Get a sub-feature by its ID

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Sub-Feature ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}

Delete sub-feature

Soft delete a sub-feature

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Sub-Feature ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "message": "string",
  • "success": true
}

Change sub-feature status

Change the status of a sub-feature (activate/deactivate)

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: 01J5C2D3E4F5G6H7I8J9K0L1M2

Sub-Feature ID

Request Body schema: application/json
required

Sub-feature status change request

status
required
string
Enum: "active" "inactive"

Responses

Request samples

Content type
application/json
{
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "success": true
}