> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siro.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an API client

> Creates an API client for the organization and returns the client id and secret once. The secret cannot be retrieved later, and the client is limited to that organization and to scopes the caller already has.

Creates a [client app](/authentication) for the organization.

The `clientSecret` is returned **once**. Store it immediately — it cannot be retrieved later. To get a new secret, [rotate](/api-references/rotate-a-client-app-secret) the existing client.

Each requested scope must already be held by the caller. The client is limited to this organization.

After create, exchange `clientId` and `clientSecret` at [auth.siro.ai](/api-references/get-a-client-app-access-token).


## OpenAPI

````yaml post /v1/core/m2m-clients/{organizationId}
openapi: 3.0.0
info:
  version: 1.0.0
  title: Swagger API
servers:
  - url: https://api.siro.ai/
    description: Siro API Gateway
security: []
externalDocs:
  description: View the raw OpenAPI Specification in JSON format
  url: /swagger.json
paths:
  /v1/core/m2m-clients/{organizationId}:
    post:
      summary: Create an API client
      description: >-
        Creates an API client for the organization and returns the client id and
        secret once. The secret cannot be retrieved later, and the client is
        limited to that organization and to scopes the caller already has.
      parameters:
        - schema:
            type: string
            description: The organization this client belongs to.
          required: true
          description: The organization this client belongs to.
          name: organizationId
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  description: A display name for the client.
                scopes:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  description: >-
                    The scopes to grant. Each one must already be held by the
                    caller.
              required:
                - name
                - scopes
              additionalProperties: false
      responses:
        '200':
          description: Create an API client
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      clientId:
                        type: string
                        description: The id of the API client.
                      clientSecret:
                        type: string
                        description: >-
                          The client secret, returned only in this response and
                          not stored.
                    required:
                      - clientId
                      - clientSecret
                  cursor:
                    anyOf:
                      - type: string
                      - type: number
                      - nullable: true
                  pageSize:
                    type: number
                  limit:
                    type: number
                  total:
                    type: number
                    nullable: true
                  hasNextPage:
                    type: boolean
                required:
                  - data
        '400':
          description: Bad Request - Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message
                required:
                  - error
        '401':
          description: Unauthorized - User not authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authentication error message
                required:
                  - error
        '403':
          description: Forbidden - User does not have access
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Authorization error message
                required:
                  - error
        '404':
          description: Not Found - Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Resource not found error message
                required:
                  - error
        '422':
          description: Unprocessable Content - The request failed validation checks
          content:
            application/json:
              schema:
                type: object
                properties:
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        expected:
                          type: string
                        received:
                          type: string
                        path:
                          type: array
                          items:
                            anyOf:
                              - type: string
                              - type: number
                        message:
                          type: string
                      required:
                        - code
                        - path
                        - message
                  name:
                    type: string
                    enum:
                      - ZodError
                required:
                  - issues
                  - name
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Internal server error message
                required:
                  - error
      security:
        - SiroAuthToken: []
components:
  securitySchemes:
    SiroAuthToken:
      type: apiKey
      in: header
      name: x-siro-auth-token
      description: >-
        Access token from POST https://auth.siro.ai/oauth2/token
        (client_credentials), or a Siro OAuth access token. Send
        `x-siro-auth-token: <access-token>`.
      x-default: <access-token>

````