Skip to content
Authrim

Create a machine access principal

POST
/api/admin/machine-access/principals
Code sample: Shell / cURL 
curl --request POST \
  --url https://auth.example.com/api/admin/machine-access/principals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "client_id": "setup-tool", "display_name": "Setup Tool", "principal_type": "setup_tool", "token_ttl_seconds": 600, "permissions": [ "admin:tenants:read" ], "tenant_scopes": [ { "scope_mode": "allow", "tenant_id": "tenant_123" } ] }'

Create a machine principal with explicit permissions, tenant scopes, and token TTL.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”

Create a machine principal.

Media type application/json
object
client_id
required
string
display_name
required
string
description
string
principal_type
required
string
token_ttl_seconds
integer format: int64
permissions
required
Array<string>
tenant_scopes
required
Array<object>
object
scope_mode
required
string
Allowed values: none all allow
tenant_id
Any of:
string
Example 
{
  "client_id": "setup-tool",
  "display_name": "Setup Tool",
  "principal_type": "setup_tool",
  "token_ttl_seconds": 600,
  "permissions": [
    "admin:tenants:read"
  ],
  "tenant_scopes": [
    {
      "scope_mode": "allow",
      "tenant_id": "tenant_123"
    }
  ]
}

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Machine principal.

Media type application/json
object
principal
required
object
id
string
clientId
string
displayName
string
description
Any of:
string
principalType
string
Allowed values: setup_tool admin_ui_bff automation ci mcp_server ai_agent internal_service integration
status
string
Allowed values: active disabled deleted
tokenTtlSeconds
integer format: int64
createdAt
integer format: int64
updatedAt
integer format: int64
permissions
Array<string>
tenantScopes
Array<object>
object
scope_mode
required
string
Allowed values: none all allow
tenant_id
Any of:
string
credentials
Array<object>
object
id
string
principalId
string
kid
string
publicJwkJson
string
alg
string
Allowed values: ES256 PS256 RS256
displayName
string
description
Any of:
string
status
string
Allowed values: active rotating revoked expired
notBefore
Any of:
integer format: int64
expiresAt
Any of:
integer format: int64
createdAt
integer format: int64
updatedAt
integer format: int64
Example 
{
  "principal": {
    "id": "amp_123",
    "clientId": "setup-tool",
    "displayName": "Setup Tool",
    "description": "Automation used by setup.",
    "principalType": "setup_tool",
    "status": "active",
    "tokenTtlSeconds": 600,
    "createdAt": 1770000000000,
    "updatedAt": 1770000000000,
    "permissions": [
      "admin:tenants:read"
    ],
    "tenantScopes": [
      {
        "scopeMode": "allow",
        "tenantId": "tenant_123"
      }
    ],
    "credentials": []
  }
}

default

Section titled “default ”

Error response.

Media type application/json
object
error
string
message
string
error_description
string
key
additional properties
Example generated
{
  "error": "example",
  "message": "example",
  "error_description": "example"
}