openapi: 3.0.3
info:
  title: Truora Account API
  description: 'Truora is a Latin American identity verification, background-check, and conversational-onboarding platform. This modeled specification documents the public REST surface across four production hosts: the Checks API (background checks on people, vehicles, and companies), the Validators API (document, facial, email, and phone validation), the Digital Identity API (web and WhatsApp verification processes), and the Account API (API-key and web integration token management). All requests authenticate with a `Truora-API-Key` header.'
  termsOfService: https://www.truora.com/en/terms-and-conditions
  contact:
    name: Truora Developers
    url: https://dev.truora.com/
  version: '1.0'
servers:
- url: https://api.checks.truora.com
  description: Checks API (background checks) - default host
- url: https://api.validations.truora.com
  description: Validators API (KYC validations)
- url: https://api.identity.truora.com
  description: Digital Identity API (web + WhatsApp processes)
- url: https://api.account.truora.com
  description: Account API (API keys and web integration tokens)
security:
- TruoraApiKey: []
tags:
- name: Account
  description: API-key and web integration token management.
paths:
  /v1/api-keys:
    servers:
    - url: https://api.account.truora.com
    post:
      operationId: createApiKey
      tags:
      - Account
      summary: Create an API key or web integration token
      description: Issues a Truora API key. With key_type=backend the returned JWT authenticates server-to-server API calls; with key_type=web it issues a short-lived web integration token used to launch a Digital Identity process in the browser or WhatsApp flow.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateApiKeyRequest'
      responses:
        '200':
          description: API key created. The JWT is returned once.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      operationId: listApiKeys
      tags:
      - Account
      summary: List API keys
      description: Retrieves the API keys registered on the account.
      responses:
        '200':
          description: A list of API keys.
          content:
            application/json:
              schema:
                type: object
                properties:
                  api_keys:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiKey'
  /v1/api-keys/{api_key_id}:
    servers:
    - url: https://api.account.truora.com
    parameters:
    - name: api_key_id
      in: path
      required: true
      schema:
        type: string
    delete:
      operationId: deleteApiKey
      tags:
      - Account
      summary: Delete (revoke) an API key
      description: Revokes an API key so it can no longer authenticate requests.
      responses:
        '200':
          description: API key revoked.
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Unauthorized:
      description: Missing or invalid Truora-API-Key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    CreateApiKeyRequest:
      type: object
      required:
      - key_type
      properties:
        key_type:
          type: string
          enum:
          - backend
          - web
          - sdk
        grant:
          type: string
          description: Product grant, e.g. digital-identity, signals, all.
        api_key_version:
          type: string
          enum:
          - '1'
          - '2'
        country:
          type: string
    ApiKey:
      type: object
      properties:
        api_key_id:
          type: string
        api_key:
          type: string
          description: The JWT credential. Returned once at creation time.
        key_type:
          type: string
        grant:
          type: string
        creation_date:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
  securitySchemes:
    TruoraApiKey:
      type: apiKey
      in: header
      name: Truora-API-Key
      description: A JWT issued from the Truora dashboard or the /v1/api-keys endpoint, sent in the Truora-API-Key request header on every call.