InternetData Account API

openapi: 3.2.0
info:
  title: InternetData Account 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: Account
  description: Who the credential belongs to, and what it may do.
  x-displayName: Account
paths:
  /api/v1/iam/identity:
    get:
      operationId: accountIdentity
      tags:
      - Account
      summary: Identity
      description: 'The identity behind this credential: what it is, the organization it is

        scoped to, and the scopes it currently holds.


        `user` is present for an OAuth token and ABSENT for an API key, which

        has an organization but no person behind it. `credential.kind` says

        which you are holding, so a client can branch without guessing from a

        missing field.


        Narrower than what the console shows its own user on purpose: an

        integration needs a name to display and an organization to address, not

        a profile. The `scopes` array is what the credential may do RIGHT NOW,

        so a client can render its own capabilities rather than discovering

        them from a 403.'
      security:
      - BearerAuth:
        - account.read
      responses:
        '200':
          description: The caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Identity'
              examples:
                ok:
                  summary: A token granted read access
                  value:
                    rc: SUCCESS
                    user:
                      id: 3d86d1ef-f70b-4063-a3b8-f69605a8fc57
                      fullname: Ada Lovelace
                      email: ada@example.com
                    org:
                      id: 7b309476-0e70-4225-9a46-5e25650094dd
                    scopes:
                    - account.read
                    - apikeys.read
        '401':
          $ref: '#/components/responses/AccountUnauthorized'
        '403':
          $ref: '#/components/responses/AccountForbidden'
components:
  schemas:
    Identity:
      type: object
      properties:
        rc:
          type: string
        user:
          $ref: '#/components/schemas/AccountUser'
        org:
          $ref: '#/components/schemas/AccountOrgRef'
        scopes:
          type: array
          items:
            type: string
          description: What this credential may do right now.
      required:
      - rc
      - user
      - org
      - scopes
    AccountOrgRef:
      type: object
      properties:
        id:
          type: string
          format: uuid
      required:
      - id
    AccountRc:
      type: object
      properties:
        rc:
          type: string
          description: The outcome. `SUCCESS` on success; otherwise the reason.
      required:
      - rc
    AccountUser:
      type: object
      properties:
        id:
          type: string
          format: uuid
        fullname:
          type: string
        email:
          type: string
          format: email
      required:
      - id
  responses:
    AccountUnauthorized:
      description: No credential was presented, or it is not valid.
      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'
  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