> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alvys.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get an access token
> Exchange your client credentials for an access token using the OAuth 2.0 Client Credentials flow.
This endpoint lives on the Alvys authorization server (`https://auth.alvys.com`), not on the API host — the playground targets it directly. It takes no bearer token of its own; the credentials in the body *are* the authentication.
Accepts either `application/json` or `application/x-www-form-urlencoded`. Both return the same token and enforce scopes identically.
Create the Client ID and Secret in the Alvys Admin Portal under **Admin → API Access**. See [Authentication](/reference/authentication) for the full walkthrough and the scope catalog.
Use this page to get a token, then paste it into the **Authorization** field on any other endpoint in this reference to send authenticated requests.
This endpoint is on the Alvys authorization server, `https://auth.alvys.com` — not the API host. It is the one endpoint that takes no bearer token: the `client_id` and `client_secret` in the body *are* the authentication.
Create your Client ID and Secret in the Alvys Admin Portal under **Admin → API Access**. [Authentication](/reference/authentication) covers the setup walkthrough, the scope catalog, and the migration off the legacy `/api/authentication/{tenant_id}/token` flow.
Your Client Secret is a credential. Anything you type into the playground is sent to the live production authorization server, so use credentials you are willing to exercise — and never paste a secret into a shared screen or recording.
### Using the token
The response's `access_token` goes on every Public API request:
```
Authorization: Bearer YOUR_ACCESS_TOKEN
```
Tokens are valid for the `expires_in` window returned with them. Cache the token for that period rather than requesting a new one per call — the token endpoint is rate limited and will return `429` if you request one per API call.
The `scope` claim on the returned token lists what it may do, and the Public API enforces those scopes on every request. A token always carries every scope granted to your client application; see [Available Scopes](/reference/authentication#available-scopes) for the full list.
## OpenAPI
````yaml POST /oauth/token
openapi: 3.0.1
info:
title: Alvys
description: >-
Alvys provides a robust set of REST APIs to allow you to integrate Alvys
into virtually any platform. These APIs cover most of Alvys' major product
areas with additional endpoints being added regularly based on customer
requests.
contact:
name: Alvys Support
url: https://www.alvys.com/resources/contact/
version: v1
servers:
- url: https://integrations.alvys.com
description: Public API Server
- url: https://api.alvys.com/
description: Public API Server
security:
- Public: []
tags:
- name: Authentication
description: Obtain an OAuth 2.0 access token for the Alvys Public API.
- name: Carrier Settlement Statements
description: >-
Search carrier settlement statements and retrieve a single statement by
number.
- name: Carriers
description: Read carrier records, search carriers, and manage carrier documents.
- name: Customers
description: Create, read, update, delete, and search customer records.
- name: Deductions
description: >-
Create one-time deductions and search or delete existing deduction
records.
- name: DispatchPreferences
description: Dispatch preferences endpoints for reading dispatch rules and preferences.
- name: Driver Settlement Statements
description: >-
Search driver settlement statements and retrieve a single statement by
number.
- name: Drivers
description: >-
Read driver records, search drivers and driver events, and manage driver
documents.
- name: Fuel
description: Read and search fuel transactions.
- name: Invoices
description: >-
Read invoices, create carrier invoices, and record carrier and customer
payments.
- name: Loads
description: Read, update, search loads, and manage load documents and notes.
- name: Locations
description: Read and search company location details.
- name: Maintenance
description: Read and search maintenance records.
- name: Tenders
description: Create, accept, reject, cancel, update, and search inbound EDI tenders.
- name: Tolls
description: Read and search toll transactions.
- name: Trailers
description: Read trailers, search trailer events, and manage trailer documents.
- name: Trips
description: >-
Read, search trips, manage trip documents, and record stop appointments,
arrivals, and departures.
- name: Trucks
description: Read trucks, search truck events, and manage truck documents.
- name: Users
description: List and search users.
- name: Visibility
description: >-
Read inbound and outbound visibility history and search outbound
visibility errors.
- name: Webhooks
description: >-
Create, read, update, delete, enable, disable, verify, test, and rotate
secrets for webhook subscriptions; read event types, delivery logs, and
health metrics.
paths:
/oauth/token:
post:
tags:
- Authentication
summary: Issue an access token
description: >-
Exchange your client credentials for an access token using the OAuth 2.0
Client Credentials flow.
This endpoint lives on the Alvys authorization server
(`https://auth.alvys.com`), not on the API host — the playground targets
it directly. It takes no bearer token of its own; the credentials in the
body *are* the authentication.
Accepts either `application/json` or
`application/x-www-form-urlencoded`. Both return the same token and
enforce scopes identically.
Create the Client ID and Secret in the Alvys Admin Portal under **Admin
→ API Access**. See [Authentication](/reference/authentication) for the
full walkthrough and the scope catalog.
operationId: IssueAccessToken
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Alvys.Auth.TokenRequest'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/Alvys.Auth.TokenRequest'
responses:
'200':
description: An access token for the Alvys Public API.
content:
application/json:
schema:
$ref: '#/components/schemas/Alvys.Auth.TokenResponse'
'401':
description: >-
The client credentials were rejected, or a requested scope was never
granted to the client.
content:
application/json:
schema:
$ref: '#/components/schemas/Alvys.Auth.TokenError'
'429':
description: >-
Too many token requests. Cache the token until it expires rather
than requesting one per API call.
content:
application/json:
schema:
$ref: '#/components/schemas/Alvys.Auth.TokenError'
security: []
servers:
- url: https://auth.alvys.com
description: Alvys authorization server
components:
schemas:
Alvys.Auth.TokenRequest:
required:
- client_id
- client_secret
- audience
- grant_type
type: object
properties:
client_id:
type: string
description: The Client ID of your Alvys client application.
example: YOUR_CLIENT_ID
client_secret:
type: string
format: password
description: >-
The Client Secret issued alongside the Client ID. Treat it as a
credential — never expose it in front-end code.
example: YOUR_CLIENT_SECRET
audience:
type: string
description: The API the token is for. Must be `https://api.alvys.com/public/`.
default: https://api.alvys.com/public/
example: https://api.alvys.com/public/
grant_type:
type: string
description: The OAuth 2.0 grant flow. Must be `client_credentials`.
enum:
- client_credentials
default: client_credentials
scope:
type: string
description: >-
Optional and non-narrowing. The issued token always carries every
scope granted to your client application regardless of this value;
its only effect is that the request fails if you name a scope your
client was not granted. Omit it unless you want that check.
example: load:read trip:read
additionalProperties: false
Alvys.Auth.TokenResponse:
required:
- access_token
- token_type
- expires_in
type: object
properties:
access_token:
type: string
description: >-
The JWT access token. Send it as `Authorization: Bearer
` on every Public API request.
token_type:
type: string
description: Always `Bearer`.
example: Bearer
expires_in:
type: integer
format: int32
description: Lifetime of the token in seconds.
example: 86400
scope:
type: string
description: >-
Space-delimited scopes granted to the token. The Public API enforces
these on every request.
example: load:read trip:read
additionalProperties: false
Alvys.Auth.TokenError:
type: object
properties:
error:
type: string
example: access_denied
error_description:
type: string
example: Unauthorized
additionalProperties: false
securitySchemes:
Public:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
OAuth 2.0 client-credentials access token. Obtain one from
https://auth.alvys.com/oauth/token (grant_type=client_credentials,
audience=https://api.alvys.com/public/), then paste it here. The
playground sends it as `Authorization: Bearer `.
````