robase-dev Dashboard API

openapi: 3.2.0
info:
  title: Robase SMS OTP Dashboard API
  description: 'Multi-provider SMS OTP delivery and transactional SMS API with automatic

    failover and per-country routing. Send and verify one-time passwords across

    Africa and globally.


    ## Authentication


    Every endpoint under `/v1` requires an API key issued in the dashboard,

    passed as a bearer token:


    ```

    Authorization: Bearer robe_your_api_key_here

    ```


    ## Idempotency


    `POST` endpoints accept an `Idempotency-Key` header. Replaying the same key

    within 24 hours returns the original response instead of sending a second

    message, so a request that times out mid-flight can be retried safely

    without double-charging credits. The official SDKs generate a key for every

    `POST` automatically.


    ## Rate limits


    Requests are limited per client IP (100/minute) and per destination phone

    number (3 OTP sends / 10 minutes, 10 OTP verifications / 10 minutes,

    10 transactional SMS / minute). Exceeding a limit returns `429` with a

    `Retry-After` header.


    ## Errors


    Failures return a consistent envelope:


    ```json

    {"error": {"type": "insufficient_credits", "message": "insufficient credit balance"}}

    ```


    Match on `error.type` (it is stable) rather than on `error.message`, which

    is prose and may change.


    ## Languages


    `error.message` is written in your workspace''s default language. Send an

    `Accept-Language` header (`en` or `fr`) to override that for one request.

    It changes only the prose, never `error.type`.


    `Accept-Language` does not affect the text of an SMS. The OTP message body

    follows the workspace''s language setting, or the `language` field on

    `POST /v1/otp/send`. A header describing which language *you* read should

    not decide what your end user receives.


    ## Webhooks


    Dashboard-configured HTTPS callbacks. The signed body is compact JSON

    (no pretty-print, no HTML escaping of `<>&`). HMAC-SHA256 is over those

    exact bytes. Envelope and `data` objects are `WebhookEnvelope`,

    `OTPWebhookData`, `SMSWebhookData`, and `CreditWebhookData`.'
  version: 1.0.0
  contact:
    name: Robase Support
    url: https://robase.dev
servers:
- url: https://api.robase.dev
  description: Production
- url: http://localhost:8080
  description: Local development
tags:
- name: Dashboard
  description: Account endpoints used by the web app. Not part of the public SMS API.
paths:
  /internal/auth/signup:
    post:
      summary: Create an account and issue an email verification code
      description: 'Dashboard sign-up. Not part of the public SMS API. On success the

        response includes `expires_at`, the RFC3339 UTC instant when the

        verification code expires. That instant is the expiry stored for the

        code (15 minutes from issue). Error responses are unchanged and do

        not include `expires_at`.'
      operationId: signupAccount
      tags:
      - Dashboard
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - password
              - name
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
                name:
                  type: string
      responses:
        '200':
          description: Account created and a verification code issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupResponse'
        '400':
          description: The request is missing fields or the password is too weak
        '409':
          description: The account could not be created. No code is issued.
        '500':
          description: The account or the verification code could not be stored
  /internal/auth/resend-verification:
    post:
      summary: Issue a fresh email verification code
      description: 'Replaces the live verification code for an unverified account.

        `expires_at` is included only when this call stored a new code. It is

        the RFC3339 UTC expiry persisted for that code (15 minutes from

        issue). A rate-limited resend (429), an already verified account

        (409), an unknown account (400), and any other response that does

        not issue a code keep their existing body and omit `expires_at`.'
      operationId: resendEmailVerification
      tags:
      - Dashboard
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - user_id
              properties:
                user_id:
                  type: string
      responses:
        '200':
          description: A new code was stored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResendVerificationResponse'
        '400':
          description: The account was not found, or user_id was missing. No code is issued.
        '409':
          description: The email is already verified. No new code is issued.
        '429':
          description: 'Too many codes were requested. No new code is issued, so the

            body does not include `expires_at`.

            '
        '500':
          description: The previous code could not be cleared, or the new code could not be stored
components:
  schemas:
    ResendVerificationResponse:
      type: object
      description: 'Returned only when a new code was issued. Rate-limited and other

        no-code responses use their existing error bodies and omit expires_at.

        '
      required:
      - status
      - expires_at
      properties:
        status:
          type: string
          enum:
          - resent
        expires_at:
          type: string
          format: date-time
          description: 'RFC3339 UTC timestamp when the newly issued verification code

            expires. Present only on this success body, because only this

            response means a code was stored.

            '
          example: '2026-10-29T10:35:00Z'
    SignupResponse:
      type: object
      required:
      - workspace_id
      - user_id
      - slug
      - message
      - expires_at
      properties:
        workspace_id:
          type: string
        user_id:
          type: string
        slug:
          type: string
        message:
          type: string
          example: Check your email for a verification code.
        expires_at:
          type: string
          format: date-time
          description: 'RFC3339 UTC timestamp when the issued verification code expires.

            This is the expiry stored with the code, not a separately chosen duration.

            '
          example: '2026-10-29T10:35:00Z'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Your Robase API key. Starts with robe_. Include as Authorization: Bearer robe_...'