imbawallet-com Auth API

openapi: 3.2.0
info:
  title: Imbawallet Com Auth API
  license:
    name: Proprietary
    url: https://imbawallet.com
  version: '1.0'
  description: 'Operations tagged Auth across 2 of this provider''s published API definitions: agent.openapi.yaml, partner.openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://imbawallet.com
  description: Production (auth + retail /api)
tags:
- name: Auth
  description: Register, assertion JWT, webhook, HMAC
paths:
  /auth/v1/agent/register:
    post:
      operationId: registerAgent
      tags:
      - Auth
      summary: Identity-only register
      description: 'Creates an agent account and Ed25519 credential. Does **not** assign a

        TRON address and does **not** credit USDT.


        Optional `email` is the 3-D Secure mailbox (not SMS, not cardholder KYC).

        HMAC plaintext is returned **once** if `callback_url` is accepted.

        Repeat register does not return the secret.


        Caution **medium** or Agent API disabled → `503`.'
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
            example:
              public_key: '-----BEGIN PUBLIC KEY-----

                MCowBQYDK2VwAyEA...

                -----END PUBLIC KEY-----'
              email: agent-otp@example.com
      responses:
        '200':
          description: Agent identity created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterResponse'
        '400':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
    servers:
    - url: https://imbawallet.com
      description: Production (auth + retail /api)
  /auth/v1/agent/token:
    post:
      operationId: createAgentAccessToken
      tags:
      - Auth
      summary: Exchange assertion JWT for access token
      description: 'Sign a short-lived EdDSA assertion (`aud=imba-agent-api`, `iss` = decimal

        `client_id`, TTL ≤ 60s). Access token `typ=agent`, `client_id`, same JWKS

        as Partner (`GET /auth/v1/partner/jwks`).


        `under_attack` or Agent API disabled → `503` (includes this endpoint).

        Defaults: 30 assertions / min / kid, 60 / min / IP.'
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - assertion
              properties:
                assertion:
                  type: string
                  description: EdDSA JWT signed with the agent Ed25519 private key
            example:
              assertion: eyJhbGciOiJFZERTQSIsImtpZCI6Ii4uLiJ9...
      responses:
        '200':
          description: Access token issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
    servers:
    - url: https://imbawallet.com
      description: Production (auth + retail /api)
  /auth/v1/partner/jwks:
    get:
      operationId: getSharedJwks
      tags:
      - Auth
      summary: JWKS for Partner and Agent access tokens
      description: Same signing keys as Partner. Agents verify `typ=agent` access tokens against this JWKS.
      security: []
      responses:
        '200':
          description: JWK set
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
    servers:
    - url: https://imbawallet.com
      description: Production (auth + retail /api)
  /auth/v1/agent/webhook:
    patch:
      operationId: patchAgentWebhook
      tags:
      - Auth
      summary: Set webhook URL, JWE key, or OTP email
      description: 'IMBA generates the HMAC secret (CSPRNG). Plaintext is shown once.

        Email-only PATCH does not require a webhook row. Email is the 3-D Secure mailbox.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookPatchRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookPatchResponse'
        '401':
          $ref: '#/components/responses/Error'
        '400':
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    servers:
    - url: https://imbawallet.com
      description: Production (auth + retail /api)
  /auth/v1/agent/hmac/rotate:
    post:
      operationId: rotateAgentHmac
      tags:
      - Auth
      summary: Rotate HMAC secret
      description: Previous secret dies immediately. New plaintext shown once. Requires an existing callback_url (register or PATCH webhook). Without a webhook URL, 400 callback_url required before rotate.
      responses:
        '200':
          description: New HMAC secret
          content:
            application/json:
              schema:
                type: object
                properties:
                  hmac_secret:
                    type: string
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    servers:
    - url: https://imbawallet.com
      description: Production (auth + retail /api)
  /auth/v1/partner/token:
    post:
      operationId: createPartnerAccessToken
      tags:
      - Auth
      summary: Exchange assertion JWT for access token
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - assertion
              properties:
                assertion:
                  type: string
                  description: Short-lived EdDSA JWT signed with partner Ed25519 key
            example:
              assertion: eyJhbGciOiJFZERTQSIsImtpZCI6ImtleV8xIn0...
      responses:
        '200':
          description: Access token issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          $ref: '#/components/responses/Error'
    servers:
    - url: https://imbawallet.com
      description: Production
components:
  schemas:
    RegisterResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    RegisterRequest:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    TokenResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    WebhookPatchRequest:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    WebhookPatchResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
  responses:
    Error:
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
x-refined-from:
- agent.openapi.yaml
- partner.openapi.yaml