openapi: 3.0.3
info:
  title: Admin Account / Address Token API
  contact:
    name: Spree Commerce
    url: https://spreecommerce.org
    email: hello@spreecommerce.org
  description: "Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n  \"error\": {\n    \"code\": \"validation_error\",\n    \"message\": \"Validation failed\",\n    \"details\": { \"name\": [\"can't be blank\"] }\n  }\n}\n```\n"
  version: v3
servers:
- url: http://{defaultHost}
  variables:
    defaultHost:
      default: localhost:3000
tags:
- name: Token
paths:
  /spree_oauth/token:
    post:
      description: 'This endpoint creates a new Bearer Token or refreshes an existing Bearer Token.


        The `token` found in the response body is required to authorize API calls.'
      operationId: create-or-refresh-token
      responses:
        '200':
          description: Token was successfully created or refreshed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
              examples:
                Storefront User Token:
                  value:
                    access_token: SfM3k8kq5Wkc6xz6rgMlsl-mbygJ1ptq4DR0Ah51vjA
                    token_type: Bearer
                    expires_in: 7200
                    refresh_token: SqJDIwX00fehqHxS6xmb-kzqAlrYe_0EHgekMexVT8k
                    created_at: 1581873931
                Platform User Token:
                  value:
                    access_token: 2480c16561d1391ea81ca5336b651e9a29f4524f6dee8c7f3f02a600159189c3
                    token_type: Bearer
                    expires_in: 7200
                    refresh_token: f5d78642252eeb3f3001f67b196ac21a27afc030462a54060b0ebbdae2b8dc9c
                    scope: admin
                    created_at: 1539863418
                Refreshed Token:
                  value:
                    access_token: Es9lLPW2mVaDB80I-I_OdQCw3JfOT1s19YN1naFWx98
                    token_type: Bearer
                    expires_in: 7200
                    refresh_token: j92BxulqIIYtiiaBsuAM1TzGsGSVxaykT4kk8OYHGNY
                    created_at: 1581876572
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/CreateTokenBody'
              - $ref: '#/components/schemas/ClientTokenBody'
              - $ref: '#/components/schemas/RefreshTokenBody'
            examples:
              Create Storefront API User Token:
                value:
                  grant_type: password
                  username: spree@example.com
                  password: spree123
              Create Platform API User Token:
                value:
                  client_id: 7ZY15L7crVZul8i3PZPrnpOkEURK7xnXEWRZdE6K39M
                  client_secret: cxMZ0tbe604qj_13hibNmc3GDsXUQfpzHt9PvweihFc
                  grant_type: password
                  username: spree@example.com
                  password: spree123
                  scope: admin
              Create Platform API Application Token:
                value:
                  grant_type: client_credentials
                  client_id: 7ZY15L7crVZul8i3PZPrnpOkEURK7xnXEWRZdE6K39M
                  client_secret: cxMZ0tbe604qj_13hibNmc3GDsXUQfpzHt9PvweihFc
                  scope: admin
              Refresh a Token:
                value:
                  grant_type: refresh_token
                  refresh_token: SqJDIwX00fehqHxS6xmb-kzqAlrYe_0EHgekMexVT8k
          application/xml:
            schema:
              type: object
              properties: {}
        description: ''
      summary: Create or Refresh a Token
      tags:
      - Token
components:
  schemas:
    ClientTokenBody:
      type: object
      x-examples:
        example-1:
          grant_type: refresh_token
          refresh_token: SqJDIwX00fehqHxS6xmb-kzqAlrYe_0EHgekMexVT8k
      x-internal: false
      title: 'Create a new token (grant_type: client_credentials)'
      description: ''
      properties:
        grant_type:
          type: string
          example: client_credentials
          enum:
          - client_credentials
        client_id:
          type: string
          description: Use the client id
          example: 27af95fd57a424e5d01aaf5eab
        client_secret:
          type: string
          example: 1324a8d5c0ca57daf384fae39f811a5144330143301'
          description: Client secret key.
      required:
      - grant_type
      - client_id
      - client_secret
    Token:
      x-examples:
        create token:
          access_token: SfM3k8kq5Wkc6xz6rgMlsl-mbygJ1ptq4DR0Ah51vjA
          token_type: Bearer
          expires_in: 7200
          refresh_token: SqJDIwX00fehqHxS6xmb-kzqAlrYe_0EHgekMexVT8k
          created_at: 1581873931
        refresh token:
          access_token: Es9lLPW2mVaDB80I-I_OdQCw3JfOT1s19YN1naFWx98
          token_type: Bearer
          expires_in: 7200
          refresh_token: j92BxulqIIYtiiaBsuAM1TzGsGSVxaykT4kk8OYHGNY
          created_at: 1581876572
      type: object
      properties:
        access_token:
          type: string
          example: 2480c16561d1391ea81ca5336b651e9a29f4524f6dee8c7f3f02a600159189c3
        token_type:
          type: string
          example: Bearer
          default: Bearer
        expires_in:
          type: integer
          example: 7200
          description: Time (in seconds) after which the access token will expire
        refresh_token:
          type: string
          example: f5d78642252eeb3f3001f67b196ac21a27afc030462a54060b0ebbdae2b8dc9c
        scope:
          type: string
          example: admin
          default: admin
        created_at:
          type: integer
          example: 1539863418
      required:
      - access_token
      - token_type
      - expires_in
      - refresh_token
      - created_at
      x-internal: false
    RefreshTokenBody:
      type: object
      x-examples:
        example-1:
          grant_type: refresh_token
          refresh_token: SqJDIwX00fehqHxS6xmb-kzqAlrYe_0EHgekMexVT8k
      x-internal: false
      title: 'Refresh an existing token (grant_type: refresh_token)'
      description: ''
      properties:
        grant_type:
          type: string
          example: refresh_token
          enum:
          - refresh_token
        refresh_token:
          type: string
          description: Refresh token obtained from the create token response
          example: 27af95fd57a424e5d01aaf5eab1324a8d5c0ca57daf384fae39f811a5144330143301'
      required:
      - grant_type
      - refresh_token
    CreateTokenBody:
      type: object
      x-examples:
        User Token:
          grant_type: password
          username: spree@example.com
          password: spree123
        Application Token:
          grant_type: password
          username: spree@example.com
          password: spree123
          scope: admin
      x-internal: false
      title: 'Create a new token (grant_type: password)'
      description: ''
      properties:
        grant_type:
          type: string
          description: ''
          example: password
          enum:
          - password
        username:
          type: string
          description: User email address
          example: spree@example.com
        password:
          type: string
          description: User password
          example: spree123
        scope:
          type: string
          enum:
          - admin
          description: Pass the value `admin` to create a Platform User Token, allowing access to the Platform API.
          nullable: true
      required:
      - grant_type
      - username
      - password
  securitySchemes:
    api_key:
      type: apiKey
      name: x-spree-api-key
      in: header
      description: Secret API key for admin access
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for admin user authentication
x-tagGroups:
- name: Authentication
  tags:
  - Authentication
- name: Product Catalog
  tags:
  - Product Catalog
- name: Orders
  tags:
  - Orders
- name: Customers
  tags:
  - Customers
- name: Configuration
  tags:
  - Configuration