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

# Creates an API key for the authenticated service provider.

> Requires the `Organization:write` scope; keys issued with the older
`ServiceProvider:write` keep working. The new key's scopes must also be a subset of the
calling key's own, so a key can never create one more powerful than itself. Asking for a
scope the caller does not hold is rejected and names the scope.
            
Each requested scope is an explicit `"Module:verb"`; a bare module name is rejected.
The key value comes back on this response and on no other - only its hash is stored. The new
key records the key that created it, returned as `ParentApiKeyId` by
`GET /v1/api-keys`.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/api-keys
openapi: 3.0.4
info:
  title: Public API
  description: Gorelo Public API documentation.
  version: 1.0.0
servers:
  - url: https://api.usw.gorelo.io
    description: US
  - url: https://api.aue.gorelo.io
    description: Australia
security:
  - ApiKeyAuth: []
tags:
  - name: Attachments
    description: "Uploading a file, for anything that can carry one. One endpoint rather than one per record\r\ntype, because the upload itself is identical - only the record it is checked against differs."
  - name: Alerts
    description: Alerts management operations
  - name: Assets
    description: Assets management operations
  - name: Billing
    description: Billing management operations
  - name: Tickets
    description: Tickets management operations
  - name: Clients
    description: Clients management operations
  - name: Contacts
    description: Contacts management operations
  - name: Deletions
    description: Deletions management operations
  - name: Documents
    description: Documents management operations
  - name: Forms
    description: Forms management operations
  - name: Organization
    description: Organization management operations
  - name: Projects
    description: Projects management operations
paths:
  /v1/api-keys:
    post:
      tags:
        - Organization
      summary: Creates an API key for the authenticated service provider.
      description: "Requires the `Organization:write` scope; keys issued with the older\r\n`ServiceProvider:write` keep working. The new key's scopes must also be a subset of the\r\ncalling key's own, so a key can never create one more powerful than itself. Asking for a\r\nscope the caller does not hold is rejected and names the scope.\r\n            \r\nEach requested scope is an explicit `\"Module:verb\"`; a bare module name is rejected.\r\nThe key value comes back on this response and on no other - only its hash is stored. The new\r\nkey records the key that created it, returned as `ParentApiKeyId` by\r\n`GET /v1/api-keys`."
      operationId: post_v1_api-keys
      requestBody:
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyCommand'
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyCommand'
          text/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyCommand'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyCommand'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/CreateApiKeyResultBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/CreateApiKeyResultBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/CreateApiKeyResultBaseResponse'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
        '401':
          description: Unauthorized
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
        '500':
          description: Internal Server Error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ObjectBaseResponse'
components:
  schemas:
    CreateApiKeyCommand:
      type: object
      properties:
        Name:
          type: string
          description: A name to identify the key by. Required.
          example: CI pipeline
        Description:
          type: string
          description: What the key is for.
          nullable: true
        Scopes:
          type: array
          items:
            enum:
              - Organization:read
              - Organization:write
              - Organization:delete
              - Tickets:read
              - Tickets:write
              - Tickets:delete
              - Clients:read
              - Clients:write
              - Clients:delete
              - Contacts:read
              - Contacts:write
              - Contacts:delete
              - Billing:read
              - Billing:write
              - Billing:delete
              - Project:read
              - Project:write
              - Project:delete
              - Assets:read
              - Assets:write
              - Assets:delete
              - Alerts:read
              - Alerts:write
              - Alerts:delete
              - Forms:read
              - Forms:write
              - Forms:delete
              - Documents:read
              - Documents:write
              - Documents:delete
            type: string
          description: "The scopes the new key carries, each an explicit `\"Module:verb\"`. Required, and every\r\nentry must be one the calling key already holds.\r\n            \r\n\nThe valid values are published as the enum on this property. Verbs are independent -\r\n`write` does not imply `read`. Note `Project` is singular. Scopes are stored\r\nas published here, whatever casing is sent; the older `ServiceProvider:verb` is still\r\naccepted and is stored as `Organization:verb`."
          example:
            - Tickets:read
            - Tickets:write
      additionalProperties: false
      description: "Request body for creating an API key. The owning service provider and the calling key's own\r\nscopes are resolved from the request context, not from the body."
    CreateApiKeyResultBaseResponse:
      type: object
      properties:
        StatusCode:
          $ref: '#/components/schemas/HttpStatusCode'
        IsSuccess:
          type: boolean
        Data:
          $ref: '#/components/schemas/CreateApiKeyResult'
        DataContext:
          type: object
          additionalProperties: false
          nullable: true
          example: null
        Notifications:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      additionalProperties: false
    ObjectBaseResponse:
      type: object
      properties:
        StatusCode:
          $ref: '#/components/schemas/HttpStatusCode'
        IsSuccess:
          type: boolean
        Data:
          nullable: true
        DataContext:
          $ref: '#/components/schemas/ErrorDataContext'
        Notifications:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      additionalProperties: false
    HttpStatusCode:
      enum:
        - 100
        - 101
        - 102
        - 103
        - 200
        - 201
        - 202
        - 203
        - 204
        - 205
        - 206
        - 207
        - 208
        - 226
        - 300
        - 301
        - 302
        - 303
        - 304
        - 305
        - 306
        - 307
        - 308
        - 400
        - 401
        - 402
        - 403
        - 404
        - 405
        - 406
        - 407
        - 408
        - 409
        - 410
        - 411
        - 412
        - 413
        - 414
        - 415
        - 416
        - 417
        - 421
        - 422
        - 423
        - 424
        - 426
        - 428
        - 429
        - 431
        - 451
        - 500
        - 501
        - 502
        - 503
        - 504
        - 505
        - 506
        - 507
        - 508
        - 510
        - 511
      type: integer
      format: int32
    CreateApiKeyResult:
      type: object
      properties:
        Id:
          type: string
          format: uuid
        KeyValue:
          type: string
          description: "The key value itself. Only the hash is stored, so this response is the single opportunity\r\nto capture it - it cannot be read back afterwards."
        Name:
          type: string
        Description:
          type: string
          nullable: true
        Scopes:
          type: array
          items:
            type: string
        CreatedAt:
          type: string
          format: date-time
      additionalProperties: false
      description: The created key. `KeyValue` is returned here and nowhere else, ever.
    Error:
      type: object
      properties:
        Code:
          pattern: ^[0-9]{6}$
          type: string
          description: 6-digit MMTTNN error code. See the Public API error-code registry.
          example: '070101'
        Message:
          type: string
        PropertyName:
          type: string
          nullable: true
        ActionHint:
          type: string
          nullable: true
        DocUrl:
          type: string
          nullable: true
      additionalProperties: false
    ErrorDataContext:
      type: object
      properties:
        TraceId:
          type: string
          description: Request correlation id. Quote this when reporting a problem.
          nullable: true
      additionalProperties: false
      description: "The `DataContext` of an error response: carries the correlation id for the failed\r\nrequest."
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: >-
        Your Gorelo API key. See [Generate API key](/generate-api-key). If your
        data is hosted in Australia, click the base URL at the top of this page
        and select `https://api.aue.gorelo.io`.
      name: X-API-Key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.