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
}

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

{
  "error": "slow_down",
  "error_description": "<string>"
}

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

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

Authentication and permissions

Token requirements: Organization-scoped API key or Workspace-scoped API key. Send the key’s client ID and secret using HTTP Basic to obtain a token. User-based OAuth tokens are not accepted here.

Credential	Access requirements
Organization-scoped API key	Supported; no permission bundle required
Workspace-scoped API key	Supported; no permission bundle required
User-based token (OAuth)	Unsupported

Permissions joined by + are all required; or separates alternatives. Full-access keys still cannot call endpoints marked unsupported. Workspace keys must allow every workspace checked by the request. OAuth access depends on the user’s roles and resource access.

Exchange public-key credentials: Use HTTP Basic with client ID and secret and grant_type=client_credentials.

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
}

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

{
  "error": "slow_down",
  "error_description": "<string>"
}

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

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

Get started

Authentication

Endpoints

Development

Create Token

Authentication

Example Request

Using the Access Token

Scoped keys

Authentication and permissions

Authorizations

Body

Response