allratestoday-com Authentication API

openapi: 3.2.0
info:
  title: AllRatesToday Exchange Rate & Central Bank Rates…
  description: 'Live mid-market exchange rates for 160+ currencies plus official rates from 122 central banks and 4 tax authorities (ECB, the Fed, Bank of Canada, CBSL, Banxico, HMRC, US Treasury and more).


    ## Data

    - **Market rates** (`/api/rate`, `/api/v1/rates`, `/api/historical-rates`): live mid-market rates, refreshed roughly every 60 seconds.

    - **Central-bank rates** (`/api/v1/central-bank/*`, `/api/open/central-bank/*`): the official tables exactly as published by each institution, one table per publication date. History reaches back to 2000 and earlier for major sources (ECB from 1999, Bank of Canada from 1950s-era series where published).

    - **Daily Reference Rate** (`/api/open/reference-rate`, `/api/v1/reference-rate/*`): one immutable mid-market USD table per business day, fixed at 16:00 London (median of a five-minute sampling window). For index calculation, research and reporting; not a registered benchmark. Methodology: https://allratestoday.com/reference-rate/


    ## Authentication

    Most endpoints require an API key sent as `Authorization: Bearer art_live_...`. Get a free key at https://allratestoday.com/register, or self-issue a 100-call trial key with no account via `POST /api/agent/keys` (built for AI agents). Logged-in dashboard users can also authenticate with their session cookie.


    Keyless endpoints: `/api/v1/symbols` and `/api/open/central-bank/{bank}` (attribution required), plus JSON reads of `/api/public/central-bank/{bank}`.


    ## Output formats

    Endpoints that return tabular data accept `?format=json|csv|xml|xlsx` (CSV is UTF-8 with BOM; XLSX is a real Excel workbook; default json).


    ## Plans

    Free plan: latest central-bank tables included. Historical central-bank dates and time series require a paid plan. See https://allratestoday.com/pricing.'
  version: 2.2.0
  contact:
    name: AllRatesToday Support
    url: https://allratestoday.com
    email: support@allratestoday.com
servers:
- url: https://allratestoday.com
  description: Production
tags:
- name: Authentication
paths:
  /api/agent/keys:
    get:
      tags:
      - Authentication
      operationId: describeTrialKeys
      summary: How to self-issue a trial key — keyless
      description: Describes the trial-key contract (method, body, limits) so an agent that only knows the URL can use it.
      responses:
        '200':
          description: Endpoint manifest
          content:
            application/json:
              schema:
                type: object
    post:
      tags:
      - Authentication
      operationId: issueTrialKey
      summary: Self-issue a 100-call trial API key — no account, no email
      description: 'Built for AI agents and other machine callers that cannot complete the human sign-up (captcha + email verification). Returns a key with 100 lifetime calls, valid 7 days, that unlocks everything a free account gets: real-time rates, latest central-bank tables, publication calendars (historical and dated rates, market and central-bank, are on paid plans). Limits: 3 keys per IP per day, 100 per day in total. Exhausted keys answer 429 with an upgrade_url. For a lasting key register at https://allratestoday.com/register (free). Send `Content-Type: application/json` (an empty JSON object is fine); a POST without it is rejected as a cross-site form.'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                agent:
                  type: string
                  maxLength: 80
                  description: 'Optional: the agent or product requesting the key.'
                purpose:
                  type: string
                  maxLength: 200
                  description: 'Optional: one line on what the rates are for.'
        description: 'Optional fields. Always send `Content-Type: application/json`, with `{}` if you have nothing to say.'
      responses:
        '201':
          description: Trial key issued
          content:
            application/json:
              schema:
                type: object
                required:
                - api_key
                - calls_included
                - expires_at
                properties:
                  api_key:
                    type: string
                    example: art_live_k3j9x2m7q1w8e5r4t6y0u2i8o3p5a7s1
                  calls_included:
                    type: integer
                    example: 100
                  expires_at:
                    type: string
                    format: date-time
                  how_to_use:
                    type: string
                  mcp_url:
                    type: string
                    format: uri
                  included:
                    type: string
                  upgrade:
                    type: object
                    properties:
                      free_account:
                        type: string
                      paid_plans:
                        type: string
                  attribution:
                    type: string
        '429':
          description: Per-IP cap reached or too many attempts
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  retry_after_s:
                    type: integer
        '503':
          description: Today's global allocation is used up
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key from your AllRatesToday dashboard. Example: `Authorization: Bearer art_live_xxxxx`. Free keys at https://allratestoday.com/register. Agents without an account: `POST /api/agent/keys` issues a 100-call trial key instantly.'
    apiKeyQuery:
      type: apiKey
      in: query
      name: key
      description: API key as a query parameter (accepted on /api/rate only; `apiKey` is an alias)
    sessionCookie:
      type: apiKey
      in: cookie
      name: art_session
      description: Session cookie for logged-in dashboard users