Auth API

Create Token

Create a token for use across the API.

To obtain your Client ID and Client Secret, visit the API Settings page in your Serval dashboard.

Authentication

This endpoint uses HTTP Basic Authentication where:

Username: Your Client ID
Password: Your Client Secret

The Authorization header should contain Basic <base64-encoded-credentials>, where the credentials are client_id:client_secret encoded in base64.

Example Request

curl -X POST https://public.api.serval.com/v2/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "your-client-id:your-client-secret" \
  -d "grant_type=client_credentials"

Or with explicit Basic auth header:

# First, base64 encode your credentials: client_id:client_secret
# For example, if client_id=abc123 and client_secret=secret456
# echo -n "abc123:secret456" | base64
# Result: YWJjMTIzOnNlY3JldDQ1Ng==

curl -X POST https://public.api.serval.com/v2/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic YWJjMTIzOnNlY3JldDQ1Ng==" \
  -d "grant_type=client_credentials"

Using the Access Token

Once you receive the access token, use it in subsequent API requests:

curl -X GET https://public.api.serval.com/v2/workflows \
  -H "Authorization: Bearer your-access-token"

Scoped keys

If your Client ID/Secret pair comes from a scoped API key, the resulting access token is restricted to that key’s scopes. This endpoint’s request/response shape is unchanged — scoping only affects which requests the token is later authorized to make.

POST

auth

token

Create Token

curl --request POST \
  --url https://public.api.serval.com/v2/auth/token \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials

import requests

url = "https://public.api.serval.com/v2/auth/token"

payload = { "grant_type": "client_credentials" }
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/x-www-form-urlencoded"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Basic <encoded-value>',
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({grant_type: 'client_credentials'})
};

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://public.api.serval.com/v2/auth/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 => "grant_type=client_credentials",
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/x-www-form-urlencoded"
  ],
]);

$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://public.api.serval.com/v2/auth/token"

	payload := strings.NewReader("grant_type=client_credentials")

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

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/x-www-form-urlencoded")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://public.api.serval.com/v2/auth/token")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/x-www-form-urlencoded")
  .body("grant_type=client_credentials")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public.api.serval.com/v2/auth/token")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/x-www-form-urlencoded'
request.body = "grant_type=client_credentials"

response = http.request(request)
puts response.read_body

{
  "access_token": "<string>",
  "token_type": "<string>",
  "expires_in": 123
}

{
  "message": "<string>",
  "detail": {
    "type": "<string>",
    "value": "<string>",
    "debug": {}
  }
}

Authorizations

Authorization

string

header

required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Body

application/x-www-form-urlencoded

grant_type

enum<string>

Available options:

client_credentials

Response

Success

access_token

string

The access token.

token_type

string

The type of token.

expires_in

integer

The number of seconds until the token expires.

Create Token

curl --request POST \
  --url https://public.api.serval.com/v2/auth/token \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials

import requests

url = "https://public.api.serval.com/v2/auth/token"

payload = { "grant_type": "client_credentials" }
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/x-www-form-urlencoded"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Basic <encoded-value>',
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({grant_type: 'client_credentials'})
};

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

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://public.api.serval.com/v2/auth/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 => "grant_type=client_credentials",
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/x-www-form-urlencoded"
  ],
]);

$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://public.api.serval.com/v2/auth/token"

	payload := strings.NewReader("grant_type=client_credentials")

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

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/x-www-form-urlencoded")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://public.api.serval.com/v2/auth/token")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/x-www-form-urlencoded")
  .body("grant_type=client_credentials")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public.api.serval.com/v2/auth/token")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/x-www-form-urlencoded'
request.body = "grant_type=client_credentials"

response = http.request(request)
puts response.read_body

{
  "access_token": "<string>",
  "token_type": "<string>",
  "expires_in": 123
}

{
  "message": "<string>",
  "detail": {
    "type": "<string>",
    "value": "<string>",
    "debug": {}
  }
}