esimker Account API

openapi: 3.2.0
info:
  title: esimker Account API
  description: 'Prepaid travel data eSIMs. No account is needed: an order is addressed by

    the secret token from its URL. Prices are USD strings, from $1.00.


    Two ways to buy:


    - **Storefront flow** (`catalog`, `orders`): pick a plan, `POST /api/orders`, send the

    buyer to `checkout_url` to pay in crypto, then poll `GET /api/orders/{token}`

    until `status` is `ready` — the eSIM (`esim.activation_code`) is in the payload.

    - **Prepaid wallet** (`wallet`): `POST /api/wallet` mints a wallet whose secret code is

    the only credential (`X-Wallet-Code`); `POST /api/wallet/deposits` opens a top-up

    invoice and, with `currency` set, returns the coin address and the exact amount for a

    payer with no browser; `POST /api/orders` with `payment_method: "wallet"` charges the

    balance and issues at once (`client_ref` makes a retry return the same order).

    - **Reseller API** (`reseller`): white-label partners on `X-API-Key`, retail minus a

    discount; keys are issued by support.


    The wallet and the catalogue are also MCP tools at `POST https://esimker.com/api/mcp`

    (Streamable HTTP; the wallet code goes in `Authorization: Bearer`).


    The guide for agents is https://esimker.com/agents (the wallet: https://esimker.com/agents#wallet).


    **Buyer accounts** (`account`) are the storefront''s own cabinet: an address and a password

    as a second way for a person to reach their orders and wallets, on a session cookie with a

    CSRF echo. An account is optional and nothing above needs one — an agent keeps the order

    token and the wallet code, and has no use for these routes.'
  version: '1'
tags:
- name: Account
paths:
  /api/account/csrf:
    get:
      tags:
      - Account
      summary: Csrf
      description: 'The token every write echoes in `X-CSRF-Token`, also set as the readable

        `csrf` cookie. Asking again returns the same one.'
      operationId: csrf_api_account_csrf_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
                title: Response Csrf Api Account Csrf Get
  /api/account/me:
    get:
      tags:
      - Account
      summary: Me
      description: 'The signed-in account, or 401. Either way the answer carries the CSRF

        cookie, so the page that asks this first can write next.'
      operationId: me_api_account_me_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/account/sessions:
    get:
      tags:
      - Account
      summary: Sessions
      description: The browsers signed in to this account, this one marked `current`.
      operationId: sessions_api_account_sessions_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Sessions Api Account Sessions Get
  /api/account/wallets:
    get:
      tags:
      - Account
      summary: Wallets
      description: 'Every linked wallet as `GET /api/wallet` shows it — the balance, the

        ledger, the orders — reached through the session instead of the code, and

        whether its code is kept for `POST /wallets/{id}/code`.'
      operationId: wallets_api_account_wallets_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Wallets Api Account Wallets Get
    post:
      tags:
      - Account
      summary: Link Wallet
      description: 'Links the wallet whose code (or 12-word phrase) is in `X-Wallet-Code` —

        the code is the proof it is the caller''s, as it is everywhere else. The

        wallet goes on working with the code alone, and the account keeps the code,

        encrypted, to show it back to its owner against the password. Linking a

        wallet already on this account keeps its code again.'
      operationId: link_wallet_api_account_wallets_post
      parameters:
      - name: X-Wallet-Code
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Wallet-Code
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Link Wallet Api Account Wallets Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/account/orders:
    get:
      tags:
      - Account
      summary: Orders
      description: 'Every order the account holds, newest first — bought while signed in,

        claimed by the verified address, or paid from a linked wallet — each with

        its token, which is the link to its order page.'
      operationId: orders_api_account_orders_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Orders Api Account Orders Get
  /api/account/register:
    post:
      tags:
      - Account
      summary: Register
      description: 'Always "check your mailbox" — for a new address, and for one that is

        already an account (whose owner is told so by mail instead).'
      operationId: register_api_account_register_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterIn'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
                title: Response Register Api Account Register Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/account/verify:
    post:
      tags:
      - Account
      summary: Verify
      description: 'The link from the registration letter plus the password: the address is

        verified and this browser is signed in. A wrong password counts against the

        account like a wrong login does. The guest orders paid for with this

        address join the account here.'
      operationId: verify_api_account_verify_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/account/login:
    post:
      tags:
      - Account
      summary: Login
      description: '`401 invalid` for everything that is not a way in: an unknown address,

        a wrong password, an address not verified yet, a switched-off account, and

        the brake — per IP and per account — once it is on. The right password on

        an unverified address also sends a fresh link, since that buyer has

        evidently lost the first one.'
      operationId: login_api_account_login_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/account/logout:
    post:
      tags:
      - Account
      summary: Logout
      description: 'Ends this browser''s session. Always 200 — signing out of a session that

        had already ended is still signed out — and the cookie goes either way.'
      operationId: logout_api_account_logout_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/account/sessions/{session_id}/revoke:
    post:
      tags:
      - Account
      summary: Revoke Session
      description: 'Signs one browser out — a lost phone, a shared computer. Another

        account''s session is "not found", not "forbidden".'
      operationId: revoke_session_api_account_sessions__session_id__revoke_post
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: integer
          title: Session Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/account/reset:
    post:
      tags:
      - Account
      summary: Request Reset
      description: Always "check your mailbox"; the letter goes only to an account.
      operationId: request_reset_api_account_reset_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetIn'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
                title: Response Request Reset Api Account Reset Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/account/reset/confirm:
    post:
      tags:
      - Account
      summary: Confirm Reset
      description: 'The new password. Every session of the account ends — whoever was in

        with the old one is out — and this browser is signed in with the new one.

        When the reset is what verified the address, its guest orders join the

        account, as at a verification.'
      operationId: confirm_reset_api_account_reset_confirm_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetConfirmIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/account/password:
    post:
      tags:
      - Account
      summary: Change Password
      description: 'The current password and a new one. This browser stays signed in; every

        other one is signed out.'
      operationId: change_password_api_account_password_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Change Password Api Account Password Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/account/email:
    post:
      tags:
      - Account
      summary: Change Email
      description: 'A link to the new address; the account keeps the old one until the link

        is followed. "Check the new mailbox" even when the address is taken.'
      operationId: change_email_api_account_email_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailIn'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
                title: Response Change Email Api Account Email Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/account/email/confirm:
    post:
      tags:
      - Account
      summary: Confirm Email
      description: 'Following the link moves the account; the old address is told. No

        session needed — the link may well be opened on another device. The guest

        orders paid for with the new address join the account.'
      operationId: confirm_email_api_account_email_confirm_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailConfirmIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
                title: Response Confirm Email Api Account Email Confirm Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/account/delete:
    post:
      tags:
      - Account
      summary: Delete Account
      description: 'Deletes the account, against the current password: the address, the

        password, every session and every passkey. The orders stay, each reached by

        its own link, and so does every linked wallet with its balance — anonymous

        again and opened by its code alone, so a code that was only ever read here

        has to be taken down first: the kept copy goes with the account. The

        address is told in a letter, and this browser is signed out. A POST, like

        every write here: CORS lets GET and POST through and nothing else.'
      operationId: delete_account_api_account_delete_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/account/wallets/{wallet_id}/unlink:
    post:
      tags:
      - Account
      summary: Unlink Wallet
      description: 'The account stops listing the wallet and forgets the code it kept. The

        wallet, its balance and its code are untouched — it is anonymous again, not

        gone, and the code still opens it.'
      operationId: unlink_wallet_api_account_wallets__wallet_id__unlink_post
      parameters:
      - name: wallet_id
        in: path
        required: true
        schema:
          type: integer
          title: Wallet Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Unlink Wallet Api Account Wallets  Wallet Id  Unlink Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/account/wallets/{wallet_id}/code:
    post:
      tags:
      - Account
      summary: Reveal Wallet Code
      description: 'A linked wallet''s code and 12-word phrase, for the account''s owner.


        Asks for the current password, not just the session: the session reads a

        wallet but cannot spend it, and the code can — a stolen session must not

        be one step from the balance. A wrong password counts against the account

        like a wrong login, and a right one is followed by a letter to the

        account''s address: whoever read the code keeps it, so the owner hears.

        `409 code_unavailable` when no code is kept: linking the wallet again with

        its code keeps it.'
      operationId: reveal_wallet_code_api_account_wallets__wallet_id__code_post
      parameters:
      - name: wallet_id
        in: path
        required: true
        schema:
          type: integer
          title: Wallet Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevealIn'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/account/passkeys:
    get:
      tags:
      - Account
      summary: List Passkeys
      description: 'The account''s passkeys, oldest first: the name, when it was added and

        when it was last used to sign in.'
      operationId: list_passkeys_api_account_passkeys_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response List Passkeys Api Account Passkeys Get
    post:
      tags:
      - Account
      summary: Add
      description: 'What `navigator.credentials.create` produced. Answers with the new

        passkey and the whole list; a ceremony that does not verify is

        `400 invalid`. The account''s address is told: a passkey survives a password

        change, so one added by whoever has the password must not be added

        quietly.'
      operationId: add_api_account_passkeys_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Add Api Account Passkeys Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/account/passkeys/options:
    post:
      tags:
      - Account
      summary: Add Options
      description: 'The current password, then the options for `navigator.credentials.create`.

        The challenge is bound to this session and lives for a few minutes.'
      operationId: add_options_api_account_passkeys_options_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddOptionsIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Add Options Api Account Passkeys Options Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/account/passkeys/login/options:
    post:
      tags:
      - Account
      summary: Login Options
      description: 'The options for `navigator.credentials.get`. No address: whichever

        passkey of this site the device offers says whose account it is.'
      operationId: login_options_api_account_passkeys_login_options_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Login Options Api Account Passkeys Login Options Post
  /api/account/passkeys/login:
    post:
      tags:
      - Account
      summary: Login
      description: 'What `navigator.credentials.get` produced, and the same answer the

        password login gives: the account, the session cookie and the CSRF cookie —

        or `401 invalid` for everything that is not a way in.'
      operationId: login_api_account_passkeys_login_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignInIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/account/passkeys/{passkey_id}/rename:
    post:
      tags:
      - Account
      summary: Rename
      description: Another account's passkey is "not found", not "forbidden".
      operationId: rename_api_account_passkeys__passkey_id__rename_post
      parameters:
      - name: passkey_id
        in: path
        required: true
        schema:
          type: integer
          title: Passkey Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenameIn'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Rename Api Account Passkeys  Passkey Id  Rename Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/account/passkeys/{passkey_id}/remove:
    post:
      tags:
      - Account
      summary: Remove
      description: 'Gone from the account; the device may still offer it, and signing in

        with it is then refused. The last one goes as easily as any other.'
      operationId: remove_api_account_passkeys__passkey_id__remove_post
      parameters:
      - name: passkey_id
        in: path
        required: true
        schema:
          type: integer
          title: Passkey Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Remove Api Account Passkeys  Passkey Id  Remove Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    EmailConfirmIn:
      properties:
        token:
          type: string
          maxLength: 512
          minLength: 16
          pattern: ^[A-Za-z0-9_.-]+$
          title: Token
      type: object
      required:
      - token
      title: EmailConfirmIn
    PasswordIn:
      properties:
        password:
          type: string
          maxLength: 256
          title: Password
        new_password:
          type: string
          maxLength: 256
          title: New Password
      type: object
      required:
      - password
      - new_password
      title: PasswordIn
    EmailIn:
      properties:
        email:
          type: string
          maxLength: 255
          minLength: 3
          title: Email
        password:
          type: string
          maxLength: 256
          title: Password
      type: object
      required:
      - email
      - password
      title: EmailIn
    RegisterIn:
      properties:
        email:
          type: string
          maxLength: 255
          minLength: 3
          title: Email
        password:
          type: string
          maxLength: 256
          title: Password
        lang:
          anyOf:
          - type: string
            pattern: ^[A-Za-z]{2}(-[A-Za-z]{4})?$
          - type: 'null'
          title: Lang
      type: object
      required:
      - email
      - password
      title: RegisterIn
    VerifyIn:
      properties:
        token:
          type: string
          maxLength: 512
          minLength: 16
          pattern: ^[A-Za-z0-9_.-]+$
          title: Token
        password:
          type: string
          maxLength: 256
          title: Password
      type: object
      required:
      - token
      - password
      title: VerifyIn
    SignInIn:
      properties:
        credential:
          additionalProperties: true
          type: object
          title: Credential
      type: object
      required:
      - credential
      title: SignInIn
    LoginIn:
      properties:
        email:
          type: string
          maxLength: 255
          minLength: 3
          title: Email
        password:
          type: string
          maxLength: 256
          title: Password
      type: object
      required:
      - email
      - password
      title: LoginIn
    AddOptionsIn:
      properties:
        password:
          type: string
          maxLength: 256
          title: Password
      type: object
      required:
      - password
      title: AddOptionsIn
    RevealIn:
      properties:
        password:
          type: string
          maxLength: 256
          title: Password
      type: object
      required:
      - password
      title: RevealIn
    ResetIn:
      properties:
        email:
          type: string
          maxLength: 255
          minLength: 3
          title: Email
      type: object
      required:
      - email
      title: ResetIn
    AddIn:
      properties:
        credential:
          additionalProperties: true
          type: object
          title: Credential
        name:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Name
      type: object
      required:
      - credential
      title: AddIn
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ResetConfirmIn:
      properties:
        token:
          type: string
          maxLength: 512
          minLength: 16
          pattern: ^[A-Za-z0-9_.-]+$
          title: Token
        password:
          type: string
          maxLength: 256
          title: Password
      type: object
      required:
      - token
      - password
      title: ResetConfirmIn
    RenameIn:
      properties:
        name:
          type: string
          maxLength: 200
          title: Name
      type: object
      required:
      - name
      title: RenameIn
    DeleteIn:
      properties:
        password:
          type: string
          maxLength: 256
          title: Password
      type: object
      required:
      - password
      title: DeleteIn
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError