v4

latestOpenAPI 3.1.1Apache 2.02026-07-31107278570.4 KB

API Auth

Create organization API client

Creates a new API client for an organization. Returns the client details and a plain secret (available only once).

post/api/v1/organizations/{organization_id}/clients

Path parameters

organization_idstring required

Unique identifier of the organization

Request body

audiencestring[]

The intended recipients of the access tokens issued to this client. Each audience value should be a URI that identifies the API or service that will validate the token.

descriptionstring

A detailed explanation of the client's purpose and usage. This helps administrators understand what the client is used for and who manages it.

expirystring int64

Expiry time in seconds for the token generated by the client

namestring

A descriptive name for the API client that helps identify its purpose. This name is displayed in the dashboard and logs. Must be between 1 and 128 characters.

scopesstring[]

OAuth 2.0 scopes that define the permissions granted to this client. Each scope represents a specific permission or set of permissions. The client can only access resources that match its granted scopes.

Example request

{
  "audience": [
    "https://api.example.com/api/analytics",
    "https://deployment-api.acmecorp.com"
  ],
  "custom_claims": [
    {
      "key": "environment",
      "value": "production"
    },
    {
      "key": "service",
      "value": "deployment"
    }
  ],
  "description": "Service account for GitHub Actions to deploy resources to production",
  "name": "GitHub Actions Deployment Service",
  "scopes": [
    "deploy:resources",
    "read:deployments"
  ]
}

Response

API client created successfully. Returns the client ID and plain secret (only available at creation time). The client can be configured with scopes, audience values, and custom claims for fine-grained access control.

plain_secretstring

Client secret value (only returned once at creation)

Example response

{
  "client": {
    "audience": [
      "https://api.example.com"
    ],
    "client_id": "m2morg_1231234233424344",
    "create_time": "2024-01-05T14:48:00Z",
    "custom_claims": [
      {
        "key": "environment",
        "value": "production"
      }
    ],
    "description": "Service account for automated deployment processes",
    "metadata_uri": "https://example.com/client-metadata.json",
    "name": "GitHub Actions Deployment Service",
    "organization_id": "org_1231234233424344",
    "redirect_uris": [
      "https://example.com/callback"
    ],
    "resource_id": "app_1231234233424344",
    "scopes": [
      "deploy:resources",
      "read:deployments"
    ],
    "secrets": [
      {
        "create_time": "2024-01-05T14:48:00Z",
        "created_by": "user_12345",
        "expire_time": "2025-01-05T14:48:00Z",
        "id": "sec_1234abcd5678efgh",
        "last_used_time": "2024-02-15T10:30:00Z",
        "plain_secret": "sec_1234567890abcdefghijklmnopqrstuvwxyz",
        "secret_suffix": "xyzw",
        "update_time": "2024-01-10T09:12:00Z"
      }
    ],
    "update_time": "2024-01-05T14:48:00Z"
  },
  "plain_secret": "CdExsdErfccxDDssddfffgfeFHH1"
}