openapi: 3.0.1
info:
  title: Carriyo Authentication API
  description: |-
    Issues OAuth 2.0 access tokens for machine-to-machine API access. Exchange a client ID and client secret for a short-lived bearer token, then include it alongside your tenant ID and API key on every subsequent request. Client credentials — and the per-resource permissions you grant them — are managed in the Carriyo Dashboard.
  contact:
    name: Carriyo Support
    url: 'https://help.carriyo.com'
    email: support@carriyo.com
  version: '1.0'
servers:
  - url: 'https://api.carriyo.com'
    description: 'Production Server'
  - url: 'https://demo-api.carriyo.com'
    description: 'Demo Server'
tags:
  - name: authentication
    description: OAuth 2.0 token issuance. Use these credentials together with `tenant-id` and `x-api-key` on every other Carriyo API call.
paths:
  /oauth/token:
    post:
      tags:
        - authentication
      summary: Get access token
      description: |-
        Exchanges a `client_id` and `client_secret` for an access token.

        Use the returned `access_token` as a bearer token in the `Authorization` header on every subsequent Carriyo API call. Cache the token client-side until it expires; `expires_in` reports the lifetime in seconds.
      operationId: oauth-token
      requestBody:
        $ref: '#/components/requestBodies/oauth-request'
      responses:
        '200':
          $ref: '#/components/responses/oauth-success-response'
        '400':
          $ref: '#/components/responses/oauth-bad-request-response'
        '403':
          $ref: '#/components/responses/oauth-error-response'
      x-codegen-request-body-name: body
components:
  requestBodies:
    oauth-request:
      description: OAuth token request body.
      required: true
      content:
        'application/json':
          schema:
            required:
              - client_id
              - client_secret
            type: object
            properties:
              client_id:
                type: string
                description: The client ID generated in the Carriyo Dashboard
              client_secret:
                type: string
                description: The client secret generated in the Carriyo Dashboard
          examples:
            Get Access Token:
              value:
                client_id: <YOUR-CLIENT-ID>
                client_secret: <YOUR-CLIENT-SECRET>
  responses:
    oauth-error-response:
      description: Error response.
      content:
        'application/json':
          schema:
            required:
              - error
              - error_description
            type: object
            properties:
              error:
                type: string
                description: Error code.
              error_description:
                type: string
                description: Human-readable explanation.
          examples:
            Error Response:
              value:
                error: access_denied
                error_description: Unauthorized
    oauth-success-response:
      description: Success response.
      content:
        'application/json':
          schema:
            required:
              - access_token
              - expires_in
              - scope
              - token_type
            type: object
            properties:
              access_token:
                type: string
                description: OAuth access token to use as a bearer token on subsequent API calls.
              scope:
                type: string
                description: Space-separated list of permissions granted to the token.
              expires_in:
                type: number
                description: Token lifetime in seconds. Carriyo currently returns 86400 (24 hours).
              token_type:
                type: string
                description: Always `Bearer`.
          examples:
            Success Response:
              value:
                access_token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL
                scope: 'tenant:TEST merchant:ACCOUNT read:shipments create:shipments update:shipments'
                expires_in: 86400
                token_type: 'Bearer'
    oauth-bad-request-response:
      description: Bad request. `client_id` or `client_secret` is missing from the request body.
      content:
        application/json:
          schema:
            required:
              - error
              - error_description
            type: object
            properties:
              error:
                type: string
                description: The error code (`bad_request`).
              error_description:
                type: string
                description: Human-readable explanation.
          examples:
            Bad Request:
              value:
                error: bad_request
                error_description: Missing client_id or client_secret
  examples:
    oauth-response:
      summary: Success response with access token
      value:
        access_token: <ACCESS-TOKEN>
        scope: <SCOPE>
        expires_in: <DATE>
        token_type: <TYPE>
