Oneprofile API Key API

openapi: 3.2.0
info:
  contact:
    email: support@getoneprofile.ai
    name: Oneprofile Support
  description: REST API reference for Oneprofile, the GTM data layer for your CRM. Manage tables, enrichments, and integrations. Authenticate with an API key to get started.
  termsOfService: https://www.getoneprofile.ai/terms
  title: Reference | Oneprofile Apikey API
  version: 1.0.42765316646
tags:
- description: Endpoints for creating and managing API keys.
  name: API Key
paths:
  /api-keys/:
    get:
      description: List all API keys for the user. Requires a user authentication (not API key).
      operationId: list_api_keys
      parameters:
      - description: The number of items to return.
        in: query
        name: limit
        required: false
        schema:
          default: 10
          description: The number of items to return.
          maximum: 100
          minimum: 1
          title: Limit
          type: integer
      - in: query
        name: order_by
        required: false
        schema:
          $ref: '#/components/schemas/OrderingParametersForIdCreatedAtUpdatedAtName'
          default: id
          enum:
          - id
          - created_at
          - updated_at
          - name
          type: string
      - in: query
        name: order_direction
        required: false
        schema:
          default: asc
          enum:
          - asc
          - desc
          title: Order Direction
          type: string
      - description: Set the cursor to the next or previous page. You can get the cursor from the previous page's response.
        in: query
        name: cursor
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Set the cursor to the next or previous page. You can get the cursor from the previous page's response.
          title: Cursor for pagination.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_APIKeyReadSchema_'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Invalid request made to the API.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Internal server error.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Bad gateway error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Service unavailable.
      security:
      - APIKeyHeader: []
      - HTTPBearer: []
      summary: List API keys
      tags:
      - API Key
    post:
      description: 'Create a new API key for the user. Requires a user authentication (not API key).


        The response carries the key''s value, and it is the only time it is ever shown: only a hash of it is stored. Keys that can write are part of every paid plan; a workspace on the free plan can create read-only keys.


        A key never does more than the person who makes it may do: a workspace admin''s key acts as an admin, a member''s key acts as a member.'
      operationId: create_api_key
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/APIKeyCreateSchema'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIKeyCreatedSchema'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: An API key with the generated key already exists, or the workspace's plan does not allow the scope asked for.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Internal server error.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Bad gateway error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Service unavailable.
      security:
      - APIKeyHeader: []
      - HTTPBearer: []
      summary: Create an API key
      tags:
      - API Key
  /api-keys/length/:
    get:
      description: Get the number of API keys for the organization.
      operationId: count_api_keys
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIKeyCountSchema'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Invalid request made to the API.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Internal server error.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Bad gateway error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Service unavailable.
      security:
      - APIKeyHeader: []
      - HTTPBearer: []
      summary: Get the number of API keys
      tags:
      - API Key
  /api-keys/scopes/:
    get:
      description: What a new key in this workspace may be allowed to do. A workspace on a paid plan can create read or write keys; the free plan can create read keys.
      operationId: list_api_key_scopes
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_APIKeyScopeReadSchema_'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Invalid request made to the API.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Internal server error.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Bad gateway error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Service unavailable.
      security:
      - APIKeyHeader: []
      - HTTPBearer: []
      summary: List the API key scopes this workspace may create
      tags:
      - API Key
  /api-keys/{api_key_id}/:
    delete:
      description: Delete an API key by its ID. Requires a user authentication (not API key). You can delete the keys you made; a workspace admin can delete anybody's.
      operationId: delete_api_key
      parameters:
      - in: path
        name: api_key_id
        required: true
        schema:
          format: uuid
          title: Api Key Id
          type: string
      - description: Report what would be deleted, and delete nothing.
        in: query
        name: dry_run
        required: false
        schema:
          default: false
          description: Report what would be deleted, and delete nothing.
          title: Dry Run
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessfullyDeletedResponse'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: A key somebody else made, and not an admin.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: The API key was not found.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Invalid request made to the API.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Internal server error.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Bad gateway error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Service unavailable.
      security:
      - APIKeyHeader: []
      - HTTPBearer: []
      summary: Delete an API key
      tags:
      - API Key
    get:
      description: Get an API key by its ID. Requires a user authentication (not API key).
      operationId: get_api_key
      parameters:
      - in: path
        name: api_key_id
        required: true
        schema:
          format: uuid
          title: Api Key Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIKeyReadSchema'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: The API key was not found.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Invalid request made to the API.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Internal server error.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Bad gateway error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Service unavailable.
      security:
      - APIKeyHeader: []
      - HTTPBearer: []
      summary: Get an API key
      tags:
      - API Key
    patch:
      description: Update an API key by its ID. Requires a user authentication (not API key). You can change the keys you made; a workspace admin can change anybody's.
      operationId: update_api_key
      parameters:
      - in: path
        name: api_key_id
        required: true
        schema:
          format: uuid
          title: Api Key Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/APIKeyUpdateSchema'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIKeyReadSchema'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: A key somebody else made, and not an admin.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: The API key was not found.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Invalid request made to the API.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Internal server error.
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Bad gateway error.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerErrorResponse'
          description: Service unavailable.
      security:
      - APIKeyHeader: []
      - HTTPBearer: []
      summary: Update an API key
      tags:
      - API Key
components:
  schemas:
    APIKeyCountSchema:
      properties:
        count:
          description: The number of API keys for the organization.
          title: Count
          type: integer
      required:
      - count
      title: APIKeyCountSchema
      type: object
    ForbiddenResponse:
      properties:
        detail:
          description: The detail of why the request is forbidden.
          title: Detail
          type: string
      required:
      - detail
      title: ForbiddenResponse
      type: object
    UnauthorizedResponse:
      properties:
        detail:
          description: The detail of why the request is unauthorized.
          title: Detail
          type: string
      required:
      - detail
      title: UnauthorizedResponse
      type: object
    UnprocessableEntityIssue:
      properties:
        input:
          anyOf:
          - type: string
          - type: integer
          - type: number
          - type: boolean
          - items: {}
            type: array
          - additionalProperties: true
            type: object
          description: The user's input that caused the error.
          title: Input
        loc:
          description: The location of the error. Always contains 1 or 2 elements. The first element is the type of location (e.g. 'body', 'query', 'path', 'header'). The second element is the name of the field that caused the error. If the error is not related to a specific field, the second element is not present.
          items:
            type: string
          title: Loc
          type: array
        msg:
          description: The message of the error. The error message to show to the user.
          title: Msg
          type: string
        type:
          description: The type of the error. Useful for frontend code to handle different types of errors.
          title: Type
          type: string
      required:
      - loc
      - msg
      - type
      - input
      title: UnprocessableEntityIssue
      type: object
    APIKeyCreateSchema:
      properties:
        expire_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: The date and time when the API key will expire. If not provided, the API key will never expire.
          title: Expire At
        name:
          description: The unique name of the API key.
          maxLength: 255
          minLength: 1
          title: Name
          type: string
        scope:
          anyOf:
          - $ref: '#/components/schemas/APIKeyScope'
          - type: 'null'
          description: 'What the key may do. Defaults to the most the workspace''s plan allows: write on a paid plan, read on the free plan.'
      required:
      - name
      title: APIKeyCreateSchema
      type: object
    APIKeyScope:
      description: 'What a key may do.


        Two values, not a permission matrix. The thing worth stopping is a write

        nobody watched: a leaked read key exposes

        what the dashboard already shows the holder, a leaked write key spends

        credits and sends mail. A free workspace may only mint ``READ``.'
      enum:
      - read
      - write
      title: APIKeyScope
      type: string
    ServerErrorResponse:
      properties:
        detail:
          description: The detail of why the server returned an error.
          title: Detail
          type: string
      required:
      - detail
      title: ServerErrorResponse
      type: object
    APIKeyReadSchema:
      properties:
        created_at:
          format: date-time
          title: Created At
          type: string
        created_by:
          anyOf:
          - type: string
          - type: 'null'
          description: The user ID of the person who made the key, or null for a key made before makers were kept. Its maker or a workspace admin can rename or delete it.
          title: Created By
        expire_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Expire At
        id:
          format: uuid
          title: Id
          type: string
        key_prefix:
          description: The first characters of the key's value, so it can be told apart from another in a list. The value itself is shown once, when the key is created, and is not recoverable afterwards.
          title: Key Prefix
          type: string
        last_used_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: When this key last authenticated a request, to the minute.
          title: Last Used At
        name:
          title: Name
          type: string
        org_id:
          title: Org Id
          type: string
        role:
          $ref: '#/components/schemas/APIKeyRole'
          description: Whose reach the key has. A key made by a workspace admin acts as an admin; one made by a member acts as a member, and is refused what a member is refused, such as changing the plan.
        scope:
          $ref: '#/components/schemas/APIKeyScope'
          description: What the key may do. A read key may call read endpoints only; a write key may call everything the workspace's plan allows.
        updated_at:
          format: date-time
          title: Updated At
          type: string
      required:
      - id
      - org_id
      - name
      - scope
      - role
      - created_by
      - key_prefix
      - created_at
      - updated_at
      title: APIKeyReadSchema
      type: object
    PaginatedResponse_APIKeyScopeReadSchema_:
      properties:
        data:
          description: The list of ResponseItems.
          items:
            $ref: '#/components/schemas/APIKeyScopeReadSchema'
          title: Data
          type: array
        next_page_cursor:
          anyOf:
          - type: string
          - type: 'null'
          description: The cursor to the next page. If there are no more pages, this is None.
        previous_page_cursor:
          anyOf:
          - type: string
          - type: 'null'
          description: The cursor to the previous page. If there are no previous pages, this is None.
      title: PaginatedResponse[APIKeyScopeReadSchema]
      type: object
    APIKeyCreatedSchema:
      description: 'A key the moment it is made: the only response that carries the secret.


        Its own schema rather than a nullable field on ``APIKeyReadSchema``, so no read

        route can grow a path that serves the value back by accident.'
      properties:
        created_at:
          format: date-time
          title: Created At
          type: string
        created_by:
          anyOf:
          - type: string
          - type: 'null'
          description: The user ID of the person who made the key, or null for a key made before makers were kept. Its maker or a workspace admin can rename or delete it.
          title: Created By
        expire_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Expire At
        id:
          format: uuid
          title: Id
          type: string
        key:
          description: 'The key''s value. Shown here and nowhere else, ever: only a hash is stored. Copy it now; a lost key has to be replaced.'
          title: Key
          type: string
        key_prefix:
          description: The first characters of the key's value, so it can be told apart from another in a list. The value itself is shown once, when the key is created, and is not recoverable afterwards.
          title: Key Prefix
          type: string
        last_used_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: When this key last authenticated a request, to the minute.
          title: Last Used At
        name:
          title: Name
          type: string
        org_id:
          title: Org Id
          type: string
        role:
          $ref: '#/components/schemas/APIKeyRole'
          description: Whose reach the key has. A key made by a workspace admin acts as an admin; one made by a member acts as a member, and is refused what a member is refused, such as changing the plan.
        scope:
          $ref: '#/components/schemas/APIKeyScope'
          description: What the key may do. A read key may call read endpoints only; a write key may call everything the workspace's plan allows.
        updated_at:
          format: date-time
          title: Updated At
          type: string
      required:
      - id
      - org_id
      - name
      - scope
      - role
      - created_by
      - key_prefix
      - created_at
      - updated_at
      - key
      title: APIKeyCreatedSchema
      type: object
    OrderingParametersForIdCreatedAtUpdatedAtName:
      enum:
      - id
      - created_at
      - updated_at
      - name
      title: OrderingParametersForIdCreatedAtUpdatedAtName
      type: string
    APIKeyUpdateSchema:
      properties:
        expire_at:
          anyOf:
          - format: date-time
            type: string
          - {}
          - type: 'null'
          description: The date and time when the API key will expire. If not provided, the API key will never expire.
          title: Expire At
        name:
          anyOf:
          - maxLength: 255
            minLength: 1
            type: string
          - {}
          description: The unique name of the API key.
          title: Name
      title: APIKeyUpdateSchema
      type: object
    UnprocessableEntityResponse:
      properties:
        detail:
          description: The detail of the error. This is the error message to show to the user. You should also use the issues field to show more detailed error messages per field. Use this field for a single liner error message.
          title: Detail
          type: string
        issues:
          description: The issues that caused the error. There can be multiple issues. Each issue is a user-facing error message.
          items:
            $ref: '#/components/schemas/UnprocessableEntityIssue'
          title: Issues
          type: array
      required:
      - detail
      - issues
      title: UnprocessableEntityResponse
      type: object
    PaginatedResponse_APIKeyReadSchema_:
      properties:
        data:
          description: The list of ResponseItems.
          items:
            $ref: '#/components/schemas/APIKeyReadSchema'
          title: Data
          type: array
        next_page_cursor:
          anyOf:
          - type: string
          - type: 'null'
          description: The cursor to the next page. If there are no more pages, this is None.
        previous_page_cursor:
          anyOf:
          - type: string
          - type: 'null'
          description: The cursor to the previous page. If there are no previous pages, this is None.
      title: PaginatedResponse[APIKeyReadSchema]
      type: object
    APIKeyScopeReadSchema:
      description: A scope this workspace's plan lets it mint, for the create form.
      properties:
        scope:
          $ref: '#/components/schemas/APIKeyScope'
          description: A scope on offer. A workspace that does not pay gets read only.
      required:
      - scope
      title: APIKeyScopeReadSchema
      type: object
    NotFoundResponse:
      properties:
        detail:
          description: The detail of why the resource was not found.
          title: Detail
          type: string
      required:
      - detail
      title: NotFoundResponse
      type: object
    APIKeyRole:
      description: 'Whose reach a key has: the role its requests carry in the workspace (2026-11-06).


        A key never does more than the person who made it may do. A key made by a

        workspace admin acts as an admin, one made by a member acts as a member, so

        an admin-only route (changing the plan, buying credits, opening billing)

        refuses a member''s key exactly as it refuses the member. Every key made

        before this existed was an admin''s reach, and keeps it.'
      enum:
      - admin
      - member
      title: APIKeyRole
      type: string
    SuccessfullyDeletedResponse:
      properties:
        count:
          default: 1
          description: The number of resources that were deleted.
          title: Count
          type: integer
        detail:
          description: The detail of why the resource was deleted.
          title: Detail
          type: string
      required:
      - detail
      title: SuccessfullyDeletedResponse
      type: object
  securitySchemes:
    APIKeyHeader:
      in: header
      name: X-API-Key
      type: apiKey
    HTTPBearer:
      scheme: bearer
      type: http