Averray Auth API

openapi: 3.2.0
info:
  title: Averray HTTP Auth API
  version: 0.2.0
  description: Public discovery, standalone Verify, and wallet-authenticated buyer and worker operations. Work and accounts settle on Polkadot Hub mainnet; paid Verify uses Base USDC. Operator/admin and session-settlement verifier operations are intentionally excluded. Read live discovery for availability and payment terms.
servers:
- url: https://api.averray.com
  description: Public mainnet API
tags:
- name: Auth
  description: SIWE authentication and bearer-token issuance.
paths:
  /auth/nonce:
    post:
      tags:
      - Auth
      operationId: requestSiweNonce
      summary: Create a SIWE sign-in message
      description: Issues a one-time nonce and the sign-in message for an EVM H160 or native SS58 AccountId32. Sign the returned message exactly as supplied, then exchange it at POST /auth/verify. Native earning requires a verified account mapping; read the returned capabilities.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SiweNonceRequest'
            examples:
              wallet:
                value:
                  wallet: '0x1111111111111111111111111111111111111111'
      responses:
        '200':
          description: A short-lived nonce and the exact SIWE message to sign.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiweNonceResponse'
        '400':
          description: The wallet is malformed or nonce issuance could not produce a unique nonce.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many nonce requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /auth/verify:
    post:
      tags:
      - Auth
      operationId: verifySiweSignature
      summary: Exchange a SIWE signature for a bearer token
      description: 'Verifies the signed EIP-4361 message, consumes its one-time nonce, and returns the wallet-scoped JWT used as `Authorization: Bearer ` on protected routes.'
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SiweVerifyRequest'
            examples:
              signature:
                value:
                  message: 'api.averray.com wants you to sign in with your Ethereum account:

                    0x1111111111111111111111111111111111111111


                    Sign in to the Agent Platform.


                    URI: https://api.averray.com

                    Version: 1

                    Chain ID: 420420419

                    Nonce: 0123456789abcdef0123456789abcdef

                    Issued At: 2026-07-28T12:00:00.000Z

                    Expiration Time: 2026-07-28T12:05:00.000Z'
                  signature: '0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001b'
      responses:
        '200':
          description: The SIWE session was verified and a bearer JWT was issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiweVerifyResponse'
        '400':
          description: The SIWE message or signature encoding is malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: SIWE verification failed because the signature, domain, chain id, validity window, wallet binding, or one-time nonce was invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                consumedNonce:
                  value:
                    error: invalid_nonce
                    message: Nonce missing or already consumed.
                    requestId: f865d489-2400-469a-945a-3c54e74e5b9e
                chainMismatch:
                  value:
                    error: siwe_chain_mismatch
                    message: 'SIWE chain id mismatch: expected 420420419, got 1.'
                    requestId: f865d489-2400-469a-945a-3c54e74e5b9e
        '429':
          description: Too many verification attempts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SiweVerifyRequest:
      type: object
      required:
      - message
      - signature
      properties:
        message:
          type: string
          minLength: 1
          maxLength: 4096
          description: The unchanged message returned by `POST /auth/nonce`.
        signature:
          type: string
          pattern: ^(?:0x)?[0-9a-fA-F]{128,132}$
          description: EVM personal_sign signature or native Substrate signature over the unchanged returned message. The server applies the identity-specific signature format and verification.
      additionalProperties: false
    SiweNonceRequest:
      type: object
      required:
      - wallet
      properties:
        wallet:
          $ref: '#/components/schemas/WalletSignInIdentity'
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        status:
          type: string
        code:
          type: string
          description: Compatibility error-code field used by a small number of conflict responses.
        message:
          type: string
        details:
          description: Optional structured context for validation, authentication, or conflict failures.
        requestId:
          type: string
      additionalProperties: true
    SiweNonceResponse:
      type: object
      required:
      - wallet
      - nonce
      - domain
      - chainId
      - statement
      - issuedAt
      - expiresAt
      - message
      properties:
        wallet:
          $ref: '#/components/schemas/WalletSignInIdentity'
        nonce:
          type: string
          minLength: 1
        domain:
          type: string
        chainId:
          type: integer
          description: EVM chain id bound into the SIWE message. Production uses Polkadot Hub mainnet (420420419).
          example: 420420419
        statement:
          type: string
        issuedAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
        message:
          type: string
          description: Exact EIP-4361 message the wallet must sign.
      additionalProperties: false
    WalletSignInIdentity:
      description: An EVM H160 address or a native SS58 AccountId32 (checksum and identity type are validated by the server). Native subjects preserve case and earning requires a verified revive mapping.
      oneOf:
      - type: string
        pattern: ^0x[a-fA-F0-9]{40}$
      - type: string
        pattern: ^[1-9A-HJ-NP-Za-km-z]+$
        description: Valid SS58-encoded AccountId32.
    SiweVerifyResponse:
      type: object
      required:
      - token
      - wallet
      - roles
      - capabilities
      - expiresAt
      - tokenType
      properties:
        token:
          type: string
          description: 'JWT supplied on protected operations as `Authorization: Bearer <token>`.'
        wallet:
          $ref: '#/components/schemas/WalletSignInIdentity'
        roles:
          type: array
          items:
            type: string
        capabilities:
          type: array
          items:
            type: string
        expiresAt:
          type: string
          format: date-time
        tokenType:
          type: string
          const: Bearer
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT