InternetData Authorization API

openapi: 3.2.0
info:
  title: InternetData Authorization 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: Authorization
  description: Obtaining and revoking tokens.
  x-displayName: Authorization
paths:
  /.well-known/oauth-authorization-server:
    get:
      operationId: oauthMetadata
      tags:
      - Authorization
      summary: Discovery
      description: 'RFC 8414 authorization server metadata: the endpoints, the grant types

        and the scopes this server supports.


        Read this rather than hardcoding endpoints. It is also served at

        `/.well-known/openid-configuration`, identically, because several

        clients probe that path first.'
      security: []
      responses:
        '200':
          description: The server's metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OauthMetadata'
  /oauth/device_authorization:
    post:
      operationId: oauthDeviceAuthorization
      tags:
      - Authorization
      summary: Device authorization
      description: 'Starts the device flow. Show the `user_code` to the person and send them

        to `verification_uri`; `verification_uri_complete` has the code already

        embedded, which is what to open if you can open a browser at all.


        Then poll `/oauth/token`, no faster than `interval` seconds.'
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DeviceAuthorizationRequest'
      responses:
        '200':
          description: A pending device authorization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceAuthorization'
        '400':
          description: '`invalid_request`, `unauthorized_client` when the client may not use

            the device flow, or `slow_down` when this address has started too

            many authorizations.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OauthError'
        '401':
          description: '`invalid_client`: the `client_id` is not registered.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OauthError'
  /oauth/register:
    post:
      operationId: oauthRegister
      tags:
      - Authorization
      summary: Register
      description: 'RFC 7591 dynamic client registration, for a client that cannot use a

        Client ID Metadata Document. Post your client''s metadata as JSON, then

        use the `client_id` in the answer at `/oauth/authorize` and

        `/oauth/token`. Nothing is kept until a person approves your client, so

        registering again costs nothing and leaves nothing to clean up.


        Each redirect URI must be https on a public host name, or http on a

        loopback address (`127.0.0.1`, `[::1]`, `localhost`), which then

        matches on any port. A custom URI scheme is refused: use a loopback

        redirect instead. So is a host on one of our own domains.


        `client_name` is shown to the person as your client''s own claim, with

        where its redirect goes beside it. A name that renders blank, or mixes

        Latin letters with Cyrillic or Greek ones, is shown as an unnamed

        application.


        The client is public whatever you ask for: `token_endpoint_auth_method`

        comes back `none`, there is no client secret, and every authorization

        proves itself with PKCE. It may be granted `apikeys.use` at most.'
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientRegistrationRequest'
      responses:
        '201':
          description: The client, as registered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientRegistration'
        '400':
          description: '`invalid_redirect_uri` names the redirect URI refused and why, and

            `invalid_client_metadata` anything else, such as a client that

            does not use the authorization code flow. `slow_down` means this

            address registered too many clients in the last minute.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OauthError'
  /oauth/authorize:
    get:
      operationId: oauthAuthorize
      tags:
      - Authorization
      summary: Authorize
      description: 'The browser entry point for the authorization-code flow. This is a

        redirect target, not something to call from code.


        Any client may sign in without registering first by using a Client ID

        Metadata Document: make `client_id` an https URL that serves your

        client''s metadata as JSON, naming that same URL as its `client_id`,

        with `token_endpoint_auth_method` `none` and your `redirect_uris`. An

        https redirect URI must be on the same origin as the `client_id`; a

        loopback one (`http://127.0.0.1`, `http://[::1]`, `http://localhost`)

        matches on any port. Such a client is granted `apikeys.use` at most. A

        client registered at `/oauth/register` uses the `client_id` it was

        given and one of the `redirect_uris` it registered.


        An unknown `client_id` or an unregistered `redirect_uri` is shown to the

        person and never redirected, because sending an error to an address we

        have not verified belongs to you is how an open redirector works. Any

        other error in the request is shown to the person too: anyone can make a

        client, so its `redirect_uri` is verified only as its own (RFC 9700

        section 4.11.2). Only the person''s answer comes back to your

        `redirect_uri`: a `code`, or `error` `access_denied`, each with your

        `state` and `iss`.'
      security: []
      parameters:
      - name: client_id
        in: query
        required: true
        schema:
          type: string
      - name: redirect_uri
        in: query
        required: true
        schema:
          type: string
      - name: response_type
        in: query
        required: true
        schema:
          type: string
          enum:
          - code
      - name: code_challenge
        in: query
        required: true
        schema:
          type: string
      - name: code_challenge_method
        in: query
        required: true
        schema:
          type: string
          enum:
          - S256
        description: S256, named explicitly. `plain`, or no method at all, is refused rather than downgraded.
      - name: scope
        in: query
        required: false
        schema:
          type: string
      - name: state
        in: query
        required: false
        schema:
          type: string
        description: Returned unchanged. Use it to bind the response to your request.
      - name: resource
        in: query
        required: false
        schema:
          type: string
        description: 'RFC 8707. What the token is FOR, so it cannot be replayed elsewhere:

          this brand''s MCP server, the only resource it issues tokens for.

          Anything else answers `invalid_target`. A client that names none is

          given that server.

          '
      responses:
        '302':
          description: A redirect to the consent screen.
        '400':
          description: Shown to the person. No error in the request is sent to your redirect_uri.
        '429':
          description: Shown to the user. Too many authorizations from one address.
  /oauth/token:
    post:
      operationId: oauthToken
      tags:
      - Authorization
      summary: Token
      description: 'Issues tokens for three grant types: a device code, an authorization

        code and a refresh token.


        `urn:ietf:params:oauth:grant-type:device_code` polls a device

        authorization. Until the person approves it answers

        `authorization_pending`; poll faster than `interval` and it answers

        `slow_down`, which means widen your interval and keep it widened.


        `authorization_code` exchanges a code from `/oauth/authorize`, with the

        `code_verifier` matching the challenge you sent and the same

        `redirect_uri`. A code works once: presenting it again also revokes

        what the first exchange issued.


        `refresh_token` exchanges a refresh token. The presented token is

        consumed whatever happens next, so store the new one before using it.

        Presenting a consumed refresh token again ends the whole authorization,

        since it means the token was copied.'
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: Tokens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: 'An RFC 6749 error. `authorization_pending` and `slow_down` are

            normal answers while polling a device authorization, not failures.

            `access_denied` means the person refused, and `expired_token` that

            the device code is no longer valid: it expired, or it was already

            exchanged or refused. `invalid_grant` means the code, device code or

            refresh token is not valid for this `client_id`. `invalid_target`

            means `resource` names something other than what was authorized.

            `slow_down` also answers any grant when this address sends too many

            requests.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OauthError'
        '401':
          description: '`invalid_client`: the `client_id` is not registered.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OauthError'
  /oauth/revoke:
    post:
      operationId: oauthRevoke
      tags:
      - Authorization
      summary: Revoke
      description: 'RFC 7009. Always answers 200, even for a token that was never valid, so

        it can''t be used to test whether a token is live.


        Revoking a refresh token ends the whole authorization and takes its

        access tokens with it. Revoking an access token affects only that token.'
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RevokeRequest'
      responses:
        '200':
          description: Always, whatever was presented.
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    RevokeRequest:
      type: object
      properties:
        token:
          type: string
          description: An access token or a refresh token.
        client_id:
          type: string
          description: Accepted and not checked.
      required:
      - token
    TokenRequest:
      type: object
      properties:
        grant_type:
          type: string
          description: '`urn:ietf:params:oauth:grant-type:device_code`, `authorization_code` or `refresh_token`.'
        client_id:
          type: string
        device_code:
          type: string
          description: Required by the device code grant.
        code:
          type: string
          description: Required by the authorization code grant.
        code_verifier:
          type: string
          description: Required by the authorization code grant.
        redirect_uri:
          type: string
          description: 'Required by the authorization code grant: the `redirect_uri` the code was issued against, exactly.'
        resource:
          type: string
          description: 'Authorization code grant, optional: RFC 8707, and it must name what was authorized.'
        refresh_token:
          type: string
          description: Required by the refresh token grant.
      required:
      - grant_type
      - client_id
    DeviceAuthorization:
      type: object
      properties:
        device_code:
          type: string
          description: Yours. Poll with it; never show it to anyone.
        user_code:
          type: string
          description: Short and typable. This is what the person confirms.
        verification_uri:
          type: string
        verification_uri_complete:
          type: string
          description: The same page with the code already filled in.
        expires_in:
          type: integer
          description: Seconds until both codes expire.
        interval:
          type: integer
          description: Seconds between polls.
      required:
      - device_code
      - user_code
      - verification_uri
      - expires_in
      - interval
    ClientRegistrationRequest:
      type: object
      properties:
        redirect_uris:
          type: array
          items:
            type: string
          description: One to ten, each matched exactly, apart from a loopback one's port.
        client_name:
          type: string
          description: Shown to the person as your client's own claim, marked unverified, beside where its redirect goes.
        grant_types:
          type: array
          items:
            type: string
          description: Must include `authorization_code` when given.
        response_types:
          type: array
          items:
            type: string
          description: Must include `code` when given.
        token_endpoint_auth_method:
          type: string
          description: Read as `none`, whatever is sent.
      required:
      - redirect_uris
    ClientRegistration:
      type: object
      properties:
        client_id:
          type: string
        client_id_issued_at:
          type: integer
          format: int64
          description: Unix seconds. 64-bit, since 32 bits run out on 2038-01-19.
        client_name:
          type: string
          description: As the person will see it.
        redirect_uris:
          type: array
          items:
            type: string
        grant_types:
          type: array
          items:
            type: string
          description: '`authorization_code` and `refresh_token`.'
        response_types:
          type: array
          items:
            type: string
        token_endpoint_auth_method:
          type: string
          description: Always `none`.
        scope:
          type: string
          description: 'The most this client may be granted: `apikeys.use`.'
      required:
      - client_id
      - client_id_issued_at
      - client_name
      - redirect_uris
      - token_endpoint_auth_method
    OauthError:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
      required:
      - error
    OauthMetadata:
      type: object
      properties:
        issuer:
          type: string
        authorization_endpoint:
          type: string
        token_endpoint:
          type: string
        device_authorization_endpoint:
          type: string
        revocation_endpoint:
          type: string
        scopes_supported:
          type: array
          items:
            type: string
        response_types_supported:
          type: array
          items:
            type: string
        grant_types_supported:
          type: array
          items:
            type: string
        code_challenge_methods_supported:
          type: array
          items:
            type: string
        client_id_metadata_document_supported:
          type: boolean
          description: Any client may sign in with an https `client_id` serving its own metadata.
        registration_endpoint:
          type: string
          description: RFC 7591 dynamic client registration, for a client that cannot serve its own metadata.
        token_endpoint_auth_methods_supported:
          type: array
          items:
            type: string
          description: Always `none`. Every client is public and has no secret.
        authorization_response_iss_parameter_supported:
          type: boolean
          description: RFC 9207. A redirect back from the authorization endpoint carries `iss`.
        service_documentation:
          type: string
      required:
      - issuer
      - authorization_endpoint
      - token_endpoint
    DeviceAuthorizationRequest:
      type: object
      properties:
        client_id:
          type: string
        scope:
          type: string
          description: Space-delimited. Anything your client is not registered for is dropped rather than refused.
        resource:
          type: string
          description: 'RFC 8707: what the token is for.'
      required:
      - client_id
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
          description: Always `Bearer`.
        expires_in:
          type: integer
          description: Seconds until the access token expires.
        refresh_token:
          type: string
          description: Always returned. A refresh consumes the token it presents, so keep this one.
        scope:
          type: string
          description: What was actually granted, which may be narrower than what was asked for.
        mslm:apikey_id:
          type: string
          description: 'Not part of OAuth, and only for our own clients. The ID of the API

            key the person picked when they approved, returned by every grant

            while this authorization may still read that key back. Absent when

            no key was picked, or when the person''s role no longer allows

            reading keys back.

            '
        mslm:apikey:
          type: string
          description: 'Not part of OAuth, and only for our own clients: a client that signed

            in with a Client ID Metadata Document or registered itself never

            receives a key. The API

            key itself, so a device ends up holding an ordinary key. Returned by

            the device code and authorization code grants only, never by a

            refresh, and only alongside

            `mslm:apikey_id`. Absent when that key''s secret cannot be read back,

            which is the case for a key created before keys could be shown again

            in the console; a rotated key can be.

            '
      required:
      - access_token
      - token_type
      - expires_in
  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