Getting Started

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 for the full walkthrough and the scope catalog.

POST

oauth

token

Issue an access token

curl --request POST \
  --url https://auth.alvys.com/oauth/token \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "audience": "https://api.alvys.com/public/",
  "grant_type": "client_credentials",
  "scope": "load:read trip:read"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    audience: 'https://api.alvys.com/public/',
    grant_type: 'client_credentials',
    scope: 'load:read trip:read'
  })
};

fetch('https://auth.alvys.com/oauth/token', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://auth.alvys.com/oauth/token"

payload = {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://api.alvys.com/public/",
    "grant_type": "client_credentials",
    "scope": "load:read trip:read"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://auth.alvys.com/oauth/token",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'client_id' => 'YOUR_CLIENT_ID',
    'client_secret' => 'YOUR_CLIENT_SECRET',
    'audience' => 'https://api.alvys.com/public/',
    'grant_type' => 'client_credentials',
    'scope' => 'load:read trip:read'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://auth.alvys.com/oauth/token"

	payload := strings.NewReader("{\n  \"client_id\": \"YOUR_CLIENT_ID\",\n  \"client_secret\": \"YOUR_CLIENT_SECRET\",\n  \"audience\": \"https://api.alvys.com/public/\",\n  \"grant_type\": \"client_credentials\",\n  \"scope\": \"load:read trip:read\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://auth.alvys.com/oauth/token")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"client_id\": \"YOUR_CLIENT_ID\",\n  \"client_secret\": \"YOUR_CLIENT_SECRET\",\n  \"audience\": \"https://api.alvys.com/public/\",\n  \"grant_type\": \"client_credentials\",\n  \"scope\": \"load:read trip:read\"\n}")
  .asString();

{
  "access_token": "<string>",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "load:read trip:read"
}

{
  "error": "access_denied",
  "error_description": "Unauthorized"
}

{
  "error": "access_denied",
  "error_description": "Unauthorized"
}

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 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 for the full list.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

client_id

string

required

The Client ID of your Alvys client application.

Example:

"YOUR_CLIENT_ID"

client_secret

string<password>

required

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

string

default:https://api.alvys.com/public/

required

The API the token is for. Must be https://api.alvys.com/public/.

Example:

"https://api.alvys.com/public/"

grant_type

enum<string>

default:client_credentials

required

The OAuth 2.0 grant flow. Must be client_credentials.

Available options:

client_credentials

scope

string

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"

Response

An access token for the Alvys Public API.

access_token

string

required

The JWT access token. Send it as Authorization: Bearer <access_token> on every Public API request.

token_type

string

required

Always Bearer.

Example:

"Bearer"

expires_in

integer<int32>

required

Lifetime of the token in seconds.

Example:

86400

scope

string

Space-delimited scopes granted to the token. The Public API enforces these on every request.

Example:

"load:read trip:read"

⌘I

Issue an access token

curl --request POST \
  --url https://auth.alvys.com/oauth/token \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "audience": "https://api.alvys.com/public/",
  "grant_type": "client_credentials",
  "scope": "load:read trip:read"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    audience: 'https://api.alvys.com/public/',
    grant_type: 'client_credentials',
    scope: 'load:read trip:read'
  })
};

fetch('https://auth.alvys.com/oauth/token', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://auth.alvys.com/oauth/token"

payload = {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://api.alvys.com/public/",
    "grant_type": "client_credentials",
    "scope": "load:read trip:read"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://auth.alvys.com/oauth/token",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'client_id' => 'YOUR_CLIENT_ID',
    'client_secret' => 'YOUR_CLIENT_SECRET',
    'audience' => 'https://api.alvys.com/public/',
    'grant_type' => 'client_credentials',
    'scope' => 'load:read trip:read'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://auth.alvys.com/oauth/token"

	payload := strings.NewReader("{\n  \"client_id\": \"YOUR_CLIENT_ID\",\n  \"client_secret\": \"YOUR_CLIENT_SECRET\",\n  \"audience\": \"https://api.alvys.com/public/\",\n  \"grant_type\": \"client_credentials\",\n  \"scope\": \"load:read trip:read\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://auth.alvys.com/oauth/token")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"client_id\": \"YOUR_CLIENT_ID\",\n  \"client_secret\": \"YOUR_CLIENT_SECRET\",\n  \"audience\": \"https://api.alvys.com/public/\",\n  \"grant_type\": \"client_credentials\",\n  \"scope\": \"load:read trip:read\"\n}")
  .asString();

{
  "access_token": "<string>",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "load:read trip:read"
}

{
  "error": "access_denied",
  "error_description": "Unauthorized"
}

{
  "error": "access_denied",
  "error_description": "Unauthorized"
}

​Using the token

Authorizations

Body

Response

Using the token