openapi: 3.0.0
info:
  version: '1'
  title: Kinde Account API Keys API
  description: '

    Provides endpoints to operate on an authenticated user.


    ## Intro


    ## How to use


    1. Get a user access token - this can be obtained when a user signs in via the methods you''ve setup in Kinde (e.g. Google, passwordless, etc).


    2. Call one of the endpoints below using the user access token in the Authorization header as a Bearer token. Typically, you can use the `getToken` command in the relevant SDK.

    '
  termsOfService: https://docs.kinde.com/trust-center/agreements/terms-of-service/
  contact:
    name: Kinde Support Team
    email: support@kinde.com
    url: https://docs.kinde.com
tags:
- name: API Keys
  x-displayName: API Keys
paths:
  /api/v1/api_keys:
    servers: []
    get:
      tags:
      - API Keys
      operationId: getApiKeys
      x-scope: read:api_keys
      summary: Get API keys
      description: "Returns a list of API keys.\n\n<div>\n  <code>read:api_keys</code>\n</div>\n"
      parameters:
      - name: page_size
        in: query
        description: Number of results per page. Defaults to 50 if parameter not sent.
        schema:
          type: integer
          nullable: true
      - name: starting_after
        in: query
        description: The ID of the API key to start after.
        schema:
          type: string
          nullable: true
      - name: key_type
        in: query
        description: Filter by API key type (organization or user).
        schema:
          type: string
          enum:
          - organization
          - user
          nullable: true
      - name: status
        in: query
        description: Filter by API key status (active, inactive, revoked).
        schema:
          type: string
          enum:
          - active
          - inactive
          - revoked
          nullable: true
      - name: user_id
        in: query
        description: Filter by user ID to get API keys associated with a specific user.
        schema:
          type: string
          nullable: true
      - name: org_code
        in: query
        description: Filter by organization code to get API keys associated with a specific organization.
        schema:
          type: string
          nullable: true
      responses:
        '200':
          description: API keys successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_api_keys_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
    post:
      tags:
      - API Keys
      operationId: createApiKey
      x-scope: create:api_keys
      summary: Create API key
      description: "Create a new API key.\n\n<div>\n  <code>create:api_keys</code>\n</div>\n"
      requestBody:
        description: API key details.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: The name of the API key.
                  type: string
                  nullable: false
                type:
                  description: The entity type that will use this API key.
                  type: string
                  enum:
                  - user
                  - organization
                  - environment
                  nullable: false
                api_id:
                  description: The ID of the API this key is associated with.
                  type: string
                  nullable: false
                scope_ids:
                  description: Array of scope IDs to associate with this API key.
                  type: array
                  items:
                    type: string
                  nullable: true
                user_id:
                  description: The ID of the user to associate with this API key (for user-level keys).
                  type: string
                  nullable: true
                org_code:
                  description: The organization code to associate with this API key (for organization-level keys).
                  type: string
                  nullable: true
              required:
              - name
              - api_id
              - type
      responses:
        '201':
          description: API key successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_api_key_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
  /api/v1/api_keys/{key_id}:
    servers: []
    get:
      tags:
      - API Keys
      operationId: getApiKey
      x-scope: read:api_keys
      summary: Get API key
      description: "Retrieve API key details by ID.\n\n<div>\n  <code>read:api_keys</code>\n</div>\n"
      parameters:
      - name: key_id
        in: path
        description: The ID of the API key.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: API key successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_api_key_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
    delete:
      tags:
      - API Keys
      operationId: deleteApiKey
      x-scope: delete:api_keys
      summary: Delete API key
      description: "Delete an API key.\n\n<div>\n  <code>delete:api_keys</code>\n</div>\n"
      parameters:
      - name: key_id
        in: path
        description: The ID of the API key.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: API key successfully deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
    put:
      tags:
      - API Keys
      operationId: rotateApiKey
      x-scope: update:api_keys
      summary: Rotate API key
      description: "Rotate an API key to generate a new key while maintaining the same permissions and associations.\n\n<div>\n  <code>update:api_keys</code>\n</div>\n"
      parameters:
      - name: key_id
        in: path
        description: The ID of the API key to rotate.
        required: true
        schema:
          type: string
      responses:
        '201':
          description: API key successfully rotated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rotate_api_key_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
  /api/v1/api_keys/verify:
    servers: []
    post:
      tags:
      - API Keys
      operationId: verifyApiKey
      summary: Verify API key
      description: 'Verify an API key (public endpoint, no authentication required).

        '
      requestBody:
        description: API key verification details.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                api_key:
                  description: The API key to verify.
                  type: string
                  nullable: false
              required:
              - api_key
      responses:
        '200':
          description: API key verification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/verify_api_key_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '401':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
components:
  schemas:
    rotate_api_key_response:
      type: object
      properties:
        code:
          type: string
          description: Response code.
          example: API_KEY_ROTATED
        message:
          type: string
          description: Response message.
          example: API key rotated successfully
        api_key:
          type: object
          properties:
            id:
              type: string
              description: The unique ID for the API key.
              example: api_key_0195ac80a14e8d71f42b98e75d3c61ad
            key:
              type: string
              description: The new API key value (only shown once).
              example: k_live_1234567890abcdef1234567890abcdef
    create_api_key_response:
      type: object
      properties:
        message:
          type: string
          description: A Kinde generated message.
          example: API key created
        code:
          type: string
          description: A Kinde generated status code.
          example: API_KEY_CREATED
        api_key:
          type: object
          properties:
            id:
              description: The unique ID for the API key.
              type: string
              example: api_key_0195ac80a14e8d71f42b98e75d3c61ad
            key:
              description: The API key value (only shown once on creation).
              type: string
              example: k_live_1234567890abcdef
    error:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        message:
          type: string
          description: Error message.
    not_found_response:
      type: object
      properties:
        errors:
          type: object
          properties:
            code:
              type: string
              example: ROUTE_NOT_FOUND
            message:
              type: string
              example: The requested API route does not exist
    success_response:
      type: object
      properties:
        message:
          type: string
          example: Success
        code:
          type: string
          example: OK
    error_response:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
    get_api_keys_response:
      type: object
      properties:
        code:
          type: string
          description: Response code.
          example: OK
        message:
          type: string
          description: Response message.
          example: Success
        has_more:
          description: Whether more records exist.
          type: boolean
        api_keys:
          type: array
          items:
            type: object
            properties:
              id:
                description: The unique ID for the API key.
                type: string
                example: api_key_0195ac80a14e8d71f42b98e75d3c61ad
              name:
                type: string
                description: The API key's name.
                example: My API Key
              type:
                type: string
                description: The type of API key.
                example: organization
              status:
                type: string
                description: The status of the API key.
                example: active
              key_prefix:
                type: string
                description: The first 6 characters of the API key for identification.
                example: kinde_
              key_suffix:
                type: string
                description: The last 4 characters of the API key for identification.
                example: abcd
                nullable: true
              created_on:
                type: string
                format: date-time
                description: When the API key was created.
                example: '2024-11-18T13:32:03+11'
              last_verified_on:
                type: string
                format: date-time
                description: When the API key was last verified.
                example: '2024-11-18T13:32:03+11'
                nullable: true
              last_verified_ip:
                type: string
                description: The IP address from which the API key was last verified.
                example: 192.168.1.1
                nullable: true
              created_by:
                type: string
                description: The name of the user who created the API key.
                example: John Doe
                nullable: true
              api_ids:
                type: array
                description: Array of API IDs associated with this key.
                items:
                  type: string
                example:
                - api_123
                - api_456
              scopes:
                type: array
                description: Array of scopes associated with this key.
                items:
                  type: string
                example:
                - read:users
                - write:users
    get_api_key_response:
      type: object
      properties:
        code:
          type: string
          description: Response code.
          example: OK
        message:
          type: string
          description: Response message.
          example: Success
        api_key:
          type: object
          properties:
            id:
              description: The unique ID for the API key.
              type: string
              example: api_key_0195ac80a14e8d71f42b98e75d3c61ad
            name:
              type: string
              description: The API key's name.
              example: My API Key
            type:
              type: string
              description: The type of API key.
              example: organization
            status:
              type: string
              description: The status of the API key.
              example: active
            key_prefix:
              type: string
              description: The first 6 characters of the API key for identification.
              example: k_live
            key_suffix:
              type: string
              description: The last 4 characters of the API key for identification.
              example: abcd
              nullable: true
            created_on:
              type: string
              format: date-time
              description: When the API key was created.
              example: '2024-11-18T13:32:03+11'
            last_verified_on:
              type: string
              format: date-time
              description: When the API key was last verified.
              example: '2024-11-18T13:32:03+11'
              nullable: true
            last_verified_ip:
              type: string
              description: The IP address from which the API key was last verified.
              example: 192.168.1.1
              nullable: true
            created_by:
              type: string
              description: The name of the user who created the API key.
              example: John Doe
              nullable: true
            api_ids:
              type: array
              description: Array of API IDs associated with this key.
              items:
                type: string
              example:
              - api_123
              - api_456
            scopes:
              type: array
              description: Array of scopes associated with this key.
              items:
                type: string
              example:
              - read:users
              - write:users
            verification_count:
              type: integer
              description: Number of times this API key has been verified.
              example: 42
              nullable: true
            organization_id:
              type: string
              description: The organization code associated with this key.
              example: org_123
              nullable: true
            user_id:
              type: string
              description: The user ID associated with this key.
              example: user_456
              nullable: true
    verify_api_key_response:
      type: object
      properties:
        code:
          type: string
          description: Response code.
          example: API_KEY_VERIFIED
        message:
          type: string
          description: Response message.
          example: API key verified
        is_valid:
          type: boolean
          description: Whether the API key is valid.
          example: true
        key_id:
          type: string
          description: The unique ID for the API key.
          example: api_key_0195ac80a14e8d71f42b98e75d3c61ad
        status:
          type: string
          description: The status of the API key.
          example: active
        scopes:
          type: array
          description: Array of scopes associated with this key.
          items:
            type: string
          example:
          - read:users
          - write:users
        org_code:
          type: string
          description: The organization code associated with this key.
          example: org_123
          nullable: true
        user_id:
          type: string
          description: The user ID associated with this key.
          example: user_456
          nullable: true
        last_verified_on:
          type: string
          format: date-time
          description: When the API key was last verified.
          example: '2024-11-18T13:32:03+11'
          nullable: true
        verification_count:
          type: integer
          description: Number of times this API key has been verified.
          example: 42
  responses:
    bad_request:
      description: Invalid request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response'
    not_found:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/not_found_response'
    forbidden:
      description: Unauthorized - invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response'
    too_many_requests:
      description: Too many requests. Request was throttled.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response'
  securitySchemes:
    kindeBearerAuth:
      description: 'To access these endpoints, you will need to use a user token. This can be obtained when your users sign in via the methods you''ve setup in Kinde (e.g. Google, passwordless, etc). Find this using the getToken command in the relevant SDK.

        '
      type: http
      scheme: bearer
      bearerFormat: JWT