Applications API

Applications in Auris represent client apps or services that integrate with the IAM platform — web apps, mobile apps, API servers, CLIs, and machine-to-machine services. Each application has a Client ID (always visible) and optionally a Client Secret (for confidential clients). Auris supports four application types: WEB, MOBILE, API, and M2M.

All endpoints in this section require the admin:all permission and the x-tenant header.

Application CRUD

GET/api/applicationsRequires: admin:all

List all applications registered in the tenant. Returns summary information for each application including type, Client ID, allowed redirect URIs, and creation date.

Query parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20)
`type`	`WEB` \| `MOBILE` \| `API` \| `M2M`	Filter by application type
`search`	string	Search by application name

Success response


{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "app_abc123",
        "name": "My Web App",
        "type": "WEB",
        "clientId": "cid_abc123",
        "redirectUris": ["https://app.yourdomain.com/callback"],
        "allowedOrigins": ["https://app.yourdomain.com"],
        "createdAt": "2025-01-10T08:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total": 3, "totalPages": 1 }
  }
}

POST/api/applicationsRequires: admin:all

Create a new application. For WEB and MOBILE types, redirectUris should be provided. For M2M type, redirectUris are not required but M2M scopes should be configured separately. A clientSecret is generated automatically and returned only in the creation response — store it securely. It cannot be retrieved again; use secret rotation to generate a new one.

Request body


{
  "name": "My Dashboard",
  "type": "WEB",
  "redirectUris": [
    "https://app.yourdomain.com/callback",
    "http://localhost:3000/callback"
  ],
  "allowedOrigins": [
    "https://app.yourdomain.com",
    "http://localhost:3000"
  ]
}

Success response


{
  "ok": true,
  "data": {
    "id": "app_def456",
    "name": "My Dashboard",
    "type": "WEB",
    "clientId": "cid_def456",
    "clientSecret": "cs_sk_...",
    "redirectUris": ["https://app.yourdomain.com/callback", "http://localhost:3000/callback"],
    "allowedOrigins": ["https://app.yourdomain.com", "http://localhost:3000"],
    "createdAt": "2025-02-18T12:00:00Z"
  }
}

The clientSecret is only returned once at creation time. Save it immediately. For public clients (browser SPAs and mobile apps), do not use the clientSecret — use PKCE instead.

Error codes

Code	HTTP	Description
`NAME_TAKEN`	409	An application with this name already exists
`VALIDATION_ERROR`	400	Invalid redirect URI format or missing required field

GET/api/applications/[id]Requires: admin:all

Get full details for a single application, including all configuration fields. The clientSecret is never returned after creation — use rotation to generate a new one.

Success response


{
  "ok": true,
  "data": {
    "id": "app_abc123",
    "name": "My Web App",
    "type": "WEB",
    "clientId": "cid_abc123",
    "redirectUris": ["https://app.yourdomain.com/callback"],
    "allowedOrigins": ["https://app.yourdomain.com"],
    "enableDeviceFlow": false,
    "enableCiba": false,
    "enableDpop": false,
    "enableM2m": false,
    "createdAt": "2025-01-10T08:00:00Z",
    "updatedAt": "2025-02-01T15:30:00Z"
  }
}

PUT/api/applications/[id]Requires: admin:all

Update an application’s configuration. All fields are optional — only provided fields are updated.

Request body


{
  "name": "My Web App v2",
  "redirectUris": [
    "https://app.yourdomain.com/callback",
    "https://staging.yourdomain.com/callback"
  ],
  "allowedOrigins": [
    "https://app.yourdomain.com",
    "https://staging.yourdomain.com"
  ],
  "enableDeviceFlow": false
}

Success response


{
  "ok": true,
  "data": {
    "id": "app_abc123",
    "name": "My Web App v2",
    "redirectUris": [
      "https://app.yourdomain.com/callback",
      "https://staging.yourdomain.com/callback"
    ]
  }
}

DELETE/api/applications/[id]Requires: admin:all

Delete an application. This revokes all active tokens issued to the application. This action cannot be undone.

Success response


{
  "ok": true,
  "data": { "deleted": true }
}

Secret Rotation

PATCH/api/applications/[id]?action=rotate-secretRequires: admin:all

Generate a new client secret for the application, immediately invalidating the previous one. The new secret is returned once. All integrations using the old secret must be updated.

Rotating the secret immediately invalidates the previous one. Any active M2M tokens obtained with the old secret continue to work until they expire, but no new tokens can be obtained.

Request: No body required.

Success response


{
  "ok": true,
  "data": {
    "clientId": "cid_abc123",
    "clientSecret": "cs_sk_new...",
    "rotatedAt": "2025-02-18T14:00:00Z"
  }
}

Custom JWT Claims

Custom claims allow you to inject additional data into access tokens issued by a specific application. Claims are resolved at token issuance time and embedded in the JWT payload.

Value Types

Type	Description	Example
`STATIC`	Fixed string value	`"plan": "enterprise"`
`USER_ATTRIBUTE`	Value from a user’s profile attribute	`"email": user.email`
`ROLE_BASED`	Value that changes based on the user’s roles	`"tier": "admin"` if role `admin`
`EXPRESSION`	Custom expression evaluated at runtime	`user.roles.includes('admin') ? 'full' : 'read'`

Reserved JWT claims (sub, iss, aud, exp, iat, jti, type, email, roles) cannot be overridden by custom claims.

GET/api/applications/[id]/custom-claimsRequires: admin:all

List all custom claims configured for an application.

Success response


{
  "ok": true,
  "data": [
    {
      "id": "claim_abc",
      "claimKey": "plan",
      "valueType": "STATIC",
      "staticValue": "enterprise",
      "isActive": true
    },
    {
      "id": "claim_def",
      "claimKey": "orgId",
      "valueType": "USER_ATTRIBUTE",
      "userAttribute": "organizationId",
      "isActive": true
    }
  ]
}

POST/api/applications/[id]/custom-claimsRequires: admin:all

Create a new custom claim for an application.

Request body — Static claim


{
  "claimKey": "plan",
  "valueType": "STATIC",
  "staticValue": "enterprise"
}

Request body — User attribute claim


{
  "claimKey": "department",
  "valueType": "USER_ATTRIBUTE",
  "userAttribute": "department"
}

Request body — Role-based claim


{
  "claimKey": "accessLevel",
  "valueType": "ROLE_BASED",
  "roleMapping": {
    "admin": "full",
    "editor": "write",
    "viewer": "read"
  }
}

Request body — Expression claim


{
  "claimKey": "isPremium",
  "valueType": "EXPRESSION",
  "expression": "user.roles.includes('premium') || user.roles.includes('admin')"
}

Success response


{
  "ok": true,
  "data": {
    "id": "claim_ghi",
    "claimKey": "plan",
    "valueType": "STATIC",
    "staticValue": "enterprise",
    "isActive": true
  }
}

Error codes

Code	HTTP	Description
`CLAIM_KEY_RESERVED`	400	Claim key is a reserved JWT field
`CLAIM_KEY_TAKEN`	409	A claim with this key already exists for this application

PATCH/api/applications/[id]/custom-claims/[claimId]Requires: admin:all

Update a custom claim. Supports partial updates — only provided fields are changed.

Request body


{
  "staticValue": "professional",
  "isActive": false
}

Success response


{
  "ok": true,
  "data": {
    "id": "claim_abc",
    "claimKey": "plan",
    "valueType": "STATIC",
    "staticValue": "professional",
    "isActive": false
  }
}

DELETE/api/applications/[id]/custom-claims/[claimId]Requires: admin:all

Delete a custom claim. The claim will no longer appear in tokens issued after deletion.

Success response


{
  "ok": true,
  "data": { "deleted": true }
}

POST/api/applications/[id]/custom-claims/previewRequires: admin:all

Preview how custom claims would be resolved for a specific user. Useful for testing claim configuration without issuing a real token.

Request body


{
  "userId": "usr_abc123"
}

Success response


{
  "ok": true,
  "data": {
    "userId": "usr_abc123",
    "resolvedClaims": {
      "plan": "enterprise",
      "department": "Engineering",
      "accessLevel": "write",
      "isPremium": false
    }
  }
}

M2M Scopes

M2M (Machine-to-Machine) scopes define what a client_credentials token is allowed to do. Scopes are free-form strings that your resource server validates.

GET/api/applications/[id]/m2m-scopesRequires: admin:all

List the M2M scopes configured for an application.

Success response


{
  "ok": true,
  "data": {
    "scopes": ["read:users", "manage:roles"],
    "allowedScopes": ["read:users", "manage:roles", "read:audit-logs"]
  }
}

scopes are the default scopes issued when scope is not specified in the token request. allowedScopes are all scopes the application is permitted to request.

POST/api/applications/[id]/m2m-scopesRequires: admin:all

Configure the M2M scopes for an application. Replaces the existing scope configuration entirely.

Request body


{
  "scopes": ["read:users"],
  "allowedScopes": ["read:users", "read:audit-logs"]
}

Success response


{
  "ok": true,
  "data": {
    "scopes": ["read:users"],
    "allowedScopes": ["read:users", "read:audit-logs"]
  }
}

After updating M2M scopes, existing tokens remain valid with their original scopes until they expire. New token requests will use the updated scope configuration.

OAuth 2.0 & OIDC — Protocol standards that applications implement
Custom JWT Claims — Configure per-application claims in access tokens
M2M Client Credentials — Server-to-server authentication for M2M apps
Applications — Manage applications from the Console

Applications API

Application CRUD

Secret Rotation

Custom JWT Claims

Value Types

M2M Scopes

Related