InternetData API keys API

openapi: 3.2.0
info:
  title: InternetData API keys API
  description: 'The InternetData API: download the databases your organization is licensed

    for, and manage the account behind them.


    See https://docs.internetdata.io for guides and https://github.com/internetdata

    for the official client libraries.'
  contact:
    name: InternetData Support
    email: support@internetdata.io
    url: https://internetdata.io
  termsOfService: https://internetdata.io/terms
  version: 2026.11.08
servers:
- url: https://internetdata.io
tags:
- name: API Keys
  description: Creating, listing and rotating credentials.
  x-displayName: API keys
paths:
  /api/v1/iam/apikeys:
    get:
      operationId: accountListApikeys
      tags:
      - API Keys
      summary: List
      description: 'Metadata only. A key''s secret is never in a list - not here and not in

        the console - because a list is the response that ends up in logs,

        caches and support tickets.


        `retrievable` says whether the secret could still be read back at all.

        A key issued before this product stored secrets recoverably was never

        kept, so `reveal` will refuse it permanently; rotating produces one

        that can be read.'
      security:
      - BearerAuth:
        - apikeys.read
      responses:
        '200':
          description: The organization's keys, newest first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApikeyList'
        '401':
          $ref: '#/components/responses/AccountUnauthorized'
        '403':
          $ref: '#/components/responses/AccountForbidden'
    post:
      operationId: accountCreateApikey
      tags:
      - API Keys
      summary: Create
      description: 'Creates a key and returns its secret.


        This is the ONLY response that ever carries the secret, and only

        because this is the moment it comes into existence. Store it now.'
      security:
      - BearerAuth:
        - apikeys.manage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountCreateApikeyRequest'
      responses:
        '200':
          description: The new key, including its secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountCreatedApikey'
        '400':
          $ref: '#/components/responses/AccountInvalid'
        '401':
          $ref: '#/components/responses/AccountUnauthorized'
        '403':
          $ref: '#/components/responses/AccountForbidden'
  /api/v1/iam/apikeys/{id}/rotate:
    post:
      operationId: accountRotateApikey
      tags:
      - API Keys
      summary: Rotate
      description: 'Replaces the secret behind a key, keeping its ID, name and settings.

        The previous secret stops working immediately. The new secret comes

        back in the answer, so this needs `apikeys.reveal` as well as

        `apikeys.manage`.'
      security:
      - BearerAuth:
        - apikeys.manage
        - apikeys.reveal
      parameters:
      - $ref: '#/components/parameters/ApikeyIdParam'
      responses:
        '200':
          description: The key, with its new secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountCreatedApikey'
        '401':
          $ref: '#/components/responses/AccountUnauthorized'
        '403':
          $ref: '#/components/responses/AccountForbidden'
        '404':
          $ref: '#/components/responses/AccountNotFound'
  /api/v1/iam/apikeys/{id}/revoke:
    post:
      operationId: accountRevokeApikey
      tags:
      - API Keys
      summary: Revoke
      description: 'Stops the key working. Revocation is soft: the key stays listed with a

        `revoked_at`, because the organization still owns whatever it did while

        it was alive.'
      security:
      - BearerAuth:
        - apikeys.manage
      parameters:
      - $ref: '#/components/parameters/ApikeyIdParam'
      responses:
        '200':
          description: Revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountRc'
        '401':
          $ref: '#/components/responses/AccountUnauthorized'
        '403':
          $ref: '#/components/responses/AccountForbidden'
        '404':
          $ref: '#/components/responses/AccountNotFound'
  /api/v1/iam/apikeys/{id}/reveal:
    post:
      operationId: accountRevealApikey
      tags:
      - API Keys
      summary: Reveal
      description: 'Returns an existing key''s secret.


        Its own scope rather than part of `apikeys.manage`, because the two are

        different acts: rotating replaces a secret you never see, while this

        hands one over.


        Refused with `NOT_RETRIEVABLE` for a key issued before this product

        stored secrets recoverably - that secret was never kept, so no retry

        will ever produce it. Rotate the key instead.'
      security:
      - BearerAuth:
        - apikeys.reveal
      parameters:
      - $ref: '#/components/parameters/ApikeyIdParam'
      responses:
        '200':
          description: The key's secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountRevealedApikey'
        '401':
          $ref: '#/components/responses/AccountUnauthorized'
        '403':
          $ref: '#/components/responses/AccountForbidden'
        '404':
          description: 'No such key in this organization, or its secret was never stored

            recoverably (`NOT_RETRIEVABLE`).

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountRc'
components:
  schemas:
    ApikeyDetail:
      description: Key METADATA. Never the key itself.
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        key_prefix:
          type: string
          description: The leading, non-secret part, so a key is recognizable without storing it.
        created:
          type: string
          format: date-time
        expires:
          type:
          - string
          - 'null'
          format: date-time
        last_used_at:
          type:
          - string
          - 'null'
          format: date-time
        revoked_at:
          type:
          - string
          - 'null'
          format: date-time
        allowed_cidrs:
          type: array
          items:
            type: string
          description: Source-IP allowlist. EMPTY MEANS UNRESTRICTED, not deny-all.
        allowed_scopes:
          type: array
          items:
            type: string
        retrievable:
          type: boolean
          description: Whether this key's secret can still be read back. False permanently for a key issued before secrets were stored recoverably.
      required:
      - id
      - name
      - key_prefix
      - created
    ApikeyList:
      type: object
      properties:
        rc:
          type: string
        keys:
          type: array
          items:
            $ref: '#/components/schemas/ApikeyDetail'
      required:
      - rc
      - keys
    AccountRc:
      type: object
      properties:
        rc:
          type: string
          description: The outcome. `SUCCESS` on success; otherwise the reason.
      required:
      - rc
    AccountCreateApikeyRequest:
      type: object
      properties:
        name:
          type: string
          description: A label you will recognize later. Shown wherever the key is listed.
        allowed_scopes:
          type: array
          items:
            type: string
          description: What the new key may do. Omit for a key that carries no named scope, which is the safe default.
      required:
      - name
    AccountRevealedApikey:
      type: object
      properties:
        rc:
          type: string
        key:
          type: string
          description: The secret.
      required:
      - rc
      - key
    AccountCreatedApikey:
      type: object
      properties:
        rc:
          type: string
        id:
          type: string
          format: uuid
        name:
          type: string
        key:
          type: string
          description: The secret. Returned once, here, and never again.
        key_prefix:
          type: string
        allowed_cidrs:
          type: array
          items:
            type: string
        allowed_scopes:
          type: array
          items:
            type: string
      required:
      - rc
      - id
      - key
  responses:
    AccountUnauthorized:
      description: No credential was presented, or it is not valid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AccountRc'
    AccountInvalid:
      description: The request body is missing a required field.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AccountRc'
    AccountNotFound:
      description: No such key in this organization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AccountRc'
    AccountForbidden:
      description: 'The credential does not hold the scope this endpoint requires. The

        missing scope is deliberately not named.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AccountRc'
  parameters:
    ApikeyIdParam:
      name: id
      in: path
      required: true
      description: The key's ID, as returned by the list endpoint. Never the key itself.
      schema:
        type: string
        format: uuid
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: apikey
      description: 'UUID-format API key issued to the customer. Each key is authorized for a

        specific set of database IDs; requesting any other ID returns 403.


        v1 only. The v2 endpoints take a console-issued key as a bearer token.

        '
    BearerAuth:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer <key>`, with a key from the console. Keys are

        default-deny: each operation names the scope it needs, and an existing

        key does not gain an operation until that scope is added to it.

        '
    ApiKeyHeaderAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: '`X-Api-Key: <key>`. The same v2 key, for clients that do not set a bearer.'
    ApiKeyQueryAuth:
      type: apiKey
      in: query
      name: apikey
      description: '`?apikey=<key>`. Convenient in a browser or a curl one-liner, which is

        how a database is usually fetched; prefer a header elsewhere.


        This is the same v2 key as the other two schemes. A v1 credential is a

        different vocabulary and fails validation here, as it would anywhere.

        '
x-tagGroups:
- name: InternetData Database API
  tags:
  - Database
  - Database v2
- name: InternetData IAM API
  tags:
  - Account
  - Organization
  - API keys
- name: InternetData Authorization
  tags:
  - Authorization