Spree Commerce

Spree OAuth API

OAuth 2.0 token endpoint used to create and refresh short-lived bearer tokens for the Spree Storefront, Platform, and Admin APIs. Supports password, client_credentials, and refresh_token grants on the /spree_oauth/token path.

Spree OAuth API is one of 25 APIs that Spree Commerce publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

Tagged areas include OAuth, Authentication, and Tokens. The published artifact set on APIs.io includes API documentation and an OpenAPI specification.

Documentation GitHub OpenAPI

Documentation

📖

Documentation

https://dev-docs.spreecommerce.org/api-reference/authentication

Specifications

⚙

OpenAPI

https://raw.githubusercontent.com/api-evangelist/spree-commerce/refs/heads/main/openapi/spree-commerce-oauth-api-openapi.yml

⚙

OpenAPI

https://raw.githubusercontent.com/spree/spree/main/docs/api-reference/oauth.yml

OpenAPI Specification

openapi: 3.0.3
servers:
  - url: "https://demo.spreecommerce.org"
    description: demo
  - url: "http://localhost:3000"
    description: localhost
info:
  version: 1.0.0
  title: Authentication
  description: Spree uses oAuth based Authentication via short-lived Bearer tokens. You can either create a new one or refresh existing token.
  contact:
    name: Vendo Connect Inc.
    url: "https://getvendo.com"
    email: [email protected]
  license:
    url: "https://github.com/spree/spree/blob/main/LICENSE.md"
    name: BSD-3-Clause
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: [email protected]
                  password: spree123
              Create Platform API User Token:
                value:
                  client_id: 7ZY15L7crVZul8i3PZPrnpOkEURK7xnXEWRZdE6K39M
                  client_secret: cxMZ0tbe604qj_13hibNmc3GDsXUQfpzHt9PvweihFc
                  grant_type: password
                  username: [email protected]
                  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:
    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
    CreateTokenBody:
      type: object
      x-examples:
        User Token:
          grant_type: password
          username: [email protected]
          password: spree123
        Application Token:
          grant_type: password
          username: [email protected]
          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: [email protected]
        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
    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
    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
tags:
  - name: Token