---
updatedAt: 2026-06-23T19:21:53.000Z
agentTools:
  projectIndex: https://docs.oway.io/llms.txt
---

# Obtain access token

Exchange client credentials for an access token.

The returned token includes scopes that determine API access:
- `shipper` scope grants access to `/v1/shipper/**` endpoints
- `carrier` scope grants access to `/v1/carrier/**` endpoints
- Partners with both scopes can access both APIs with a single token

The returned token should be included in subsequent API requests as a Bearer token
in the authorization header: `authorization: Bearer {access_token}`

Tokens are valid for the duration specified in `expires_in` (seconds).
We recommend caching tokens and refreshing them before expiration.


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Oway Auth API",
    "description": "Authentication endpoint for obtaining access tokens via client credentials.",
    "contact": {
      "name": "Oway Support",
      "email": "support@oway.io"
    },
    "version": "1.0.0"
  },
  "externalDocs": {
    "description": "Oway API Developer Portal",
    "url": "https://oway.readme.io"
  },
  "servers": [
    {
      "url": "https://api.oway.io",
      "description": "Production"
    },
    {
      "url": "https://api.sandbox.oway.io",
      "description": "Sandbox Environment"
    }
  ],
  "tags": [
    {
      "name": "Authentication",
      "description": "API authentication endpoints for obtaining access tokens"
    }
  ],
  "paths": {
    "/v1/auth/token": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Obtain access token",
        "description": "Exchange client credentials for an access token.\n\nThe returned token includes scopes that determine API access:\n- `shipper` scope grants access to `/v1/shipper/**` endpoints\n- `carrier` scope grants access to `/v1/carrier/**` endpoints\n- Partners with both scopes can access both APIs with a single token\n\nThe returned token should be included in subsequent API requests as a Bearer token\nin the authorization header: `authorization: Bearer {access_token}`\n\nTokens are valid for the duration specified in `expires_in` (seconds).\nWe recommend caching tokens and refreshing them before expiration.\n",
        "operationId": "getToken",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TokenRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Token successfully generated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request: missing required fields",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized: invalid credentials",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "TokenRequest": {
        "type": "object",
        "description": "Token request containing client credentials",
        "properties": {
          "clientId": {
            "type": "string",
            "description": "Client ID provided by Oway",
            "example": "abc123def456"
          },
          "clientSecret": {
            "type": "string",
            "description": "Client secret provided by Oway",
            "example": "secret_xyz789"
          }
        },
        "required": [
          "clientId",
          "clientSecret"
        ]
      },
      "TokenResponse": {
        "type": "object",
        "description": "Successful token response",
        "properties": {
          "accessToken": {
            "type": "string",
            "description": "The access token to use for API requests",
            "example": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
          },
          "tokenType": {
            "type": "string",
            "description": "Token type (always 'Bearer')",
            "example": "Bearer"
          },
          "expiresIn": {
            "type": "integer",
            "format": "int32",
            "description": "Token validity in seconds",
            "example": 86400
          }
        }
      },
      "TokenErrorResponse": {
        "type": "object",
        "description": "Error response for token requests",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error code",
            "example": "invalid_client"
          },
          "errorDescription": {
            "type": "string",
            "description": "Human-readable error description",
            "example": "Invalid client credentials"
          }
        }
      }
    }
  },
  "x-readme": {
    "headers": [
      {
        "value": "Bearer your_bearer_token_here",
        "key": "authorization"
      },
      {
        "value": "oway_sk_your_api_key_here",
        "key": "x-oway-api-key"
      }
    ],
    "explorer-enabled": true,
    "samples-languages": [
      "go",
      "typescript",
      "java",
      "php",
      "python"
    ]
  }
}
```