API tokens
Create an API token
Issues a new client credential for your account. The response carries clientSecret exactly once — store it before doing anything else. Retrying with the same Idempotency-Key answers 200 with the token already made and no secret; if the secret has been lost, rotate the token.
State what the token reaches as either organisationIds or allOrganisations: true, never both. allOrganisations grants account-wide access — every organisation the account owns, including ones added later — and only somebody who already holds account-wide access may grant it (403 whole_customer_access_denied otherwise). name is 3 to 100 characters and unique within your account.
An account may hold 5 API tokens, counting every client credential it holds and not only the ones created here. Being over the limit revokes nothing; it only refuses a new one. Three things answer 409, told apart by message.token:
token_limit_reached— the account already holds 5 tokens. Revoke one that is no longer used, or contact support to raise the allowance.duplicate_token_name— another token in your account has that name.idempotency_key_reused— thatIdempotency-Keywas already used for a different request body.
403 billing_not_set_up when billing is not set up for the account yet — email hello@flowpayroll.ai to agree pricing and set it up. Accounts onboarded by Flow Payroll are already set up.
POST
/
api-tokens
Create an API token
curl --request POST \
--url https://api.sandbox.flowpayroll.ai/v1/administration/api-tokens \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"name": "<string>",
"organisationIds": [
"<string>"
],
"allOrganisations": true
}
'import requests
url = "https://api.sandbox.flowpayroll.ai/v1/administration/api-tokens"
payload = {
"name": "<string>",
"organisationIds": ["<string>"],
"allOrganisations": True
}
headers = {
"X-Auth-Token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Auth-Token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: '<string>', organisationIds: ['<string>'], allOrganisations: true})
};
fetch('https://api.sandbox.flowpayroll.ai/v1/administration/api-tokens', 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://api.sandbox.flowpayroll.ai/v1/administration/api-tokens",
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([
'name' => '<string>',
'organisationIds' => [
'<string>'
],
'allOrganisations' => true
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Auth-Token: <api-key>"
],
]);
$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://api.sandbox.flowpayroll.ai/v1/administration/api-tokens"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"organisationIds\": [\n \"<string>\"\n ],\n \"allOrganisations\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Auth-Token", "<api-key>")
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://api.sandbox.flowpayroll.ai/v1/administration/api-tokens")
.header("X-Auth-Token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"organisationIds\": [\n \"<string>\"\n ],\n \"allOrganisations\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.flowpayroll.ai/v1/administration/api-tokens")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Auth-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"organisationIds\": [\n \"<string>\"\n ],\n \"allOrganisations\": true\n}"
response = http.request(request)
puts response.read_body{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
]
},
"content": {
"data": {
"clientId": "<string>",
"name": "<string>",
"clientSecret": "<string>",
"organisationIds": [
"<string>"
],
"coversWholeCustomer": true,
"alreadyExisted": true
},
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
]
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
]
},
"content": {
"data": {
"clientId": "<string>",
"name": "<string>",
"clientSecret": "<string>",
"organisationIds": [
"<string>"
],
"coversWholeCustomer": true,
"alreadyExisted": true
},
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
]
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
]
},
"content": {
"data": null,
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
]
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
]
},
"content": {
"data": null,
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
]
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
]
},
"content": {
"data": null,
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
]
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
]
},
"content": {
"data": null,
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
]
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
]
},
"content": {
"data": null,
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
]
}Authorizations
FlowPayroll JWT (raw token, no Bearer prefix)
Headers
Your own key for this create, so a retry after a lost response finds what the first attempt made instead of making a second one. Any unique string up to 255 characters; a UUID is the usual choice. Send the same value on every retry of the same request, and a new value for a new one — reusing a key for a different body answers 409 idempotency_key_reused. Keys are remembered for 24 hours. Optional, and a request without one simply has no replay protection.
Maximum string length:
255Body
application/json
Issues a new API token (client credential) for your account.
Required. A display name, unique within your account.
The organisations the token reaches. State exactly one of this and allOrganisations.
Give the credential access to every organisation the account owns, including ones added later,
instead of the ones named in organisationIds. State exactly one of the two. This is the
widest grant this API makes, so only somebody who already holds account-wide access may ask for it.
Was this page helpful?
⌘I
Create an API token
curl --request POST \
--url https://api.sandbox.flowpayroll.ai/v1/administration/api-tokens \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"name": "<string>",
"organisationIds": [
"<string>"
],
"allOrganisations": true
}
'import requests
url = "https://api.sandbox.flowpayroll.ai/v1/administration/api-tokens"
payload = {
"name": "<string>",
"organisationIds": ["<string>"],
"allOrganisations": True
}
headers = {
"X-Auth-Token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Auth-Token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: '<string>', organisationIds: ['<string>'], allOrganisations: true})
};
fetch('https://api.sandbox.flowpayroll.ai/v1/administration/api-tokens', 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://api.sandbox.flowpayroll.ai/v1/administration/api-tokens",
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([
'name' => '<string>',
'organisationIds' => [
'<string>'
],
'allOrganisations' => true
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Auth-Token: <api-key>"
],
]);
$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://api.sandbox.flowpayroll.ai/v1/administration/api-tokens"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"organisationIds\": [\n \"<string>\"\n ],\n \"allOrganisations\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Auth-Token", "<api-key>")
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://api.sandbox.flowpayroll.ai/v1/administration/api-tokens")
.header("X-Auth-Token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"organisationIds\": [\n \"<string>\"\n ],\n \"allOrganisations\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.flowpayroll.ai/v1/administration/api-tokens")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Auth-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"organisationIds\": [\n \"<string>\"\n ],\n \"allOrganisations\": true\n}"
response = http.request(request)
puts response.read_body{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
]
},
"content": {
"data": {
"clientId": "<string>",
"name": "<string>",
"clientSecret": "<string>",
"organisationIds": [
"<string>"
],
"coversWholeCustomer": true,
"alreadyExisted": true
},
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
]
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
]
},
"content": {
"data": {
"clientId": "<string>",
"name": "<string>",
"clientSecret": "<string>",
"organisationIds": [
"<string>"
],
"coversWholeCustomer": true,
"alreadyExisted": true
},
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
]
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
]
},
"content": {
"data": null,
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
]
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
]
},
"content": {
"data": null,
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
]
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
]
},
"content": {
"data": null,
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
]
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
]
},
"content": {
"data": null,
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
]
}{
"message": {
"text": "<string>",
"token": "<string>",
"tokenArguments": [
{
"name": "<string>",
"value": null
}
]
},
"content": {
"data": null,
"metadata": {
"dateFormat": "<string>",
"dateTimeFormat": "<string>",
"paginationToken": "<string>"
}
},
"validationIssues": [
{
"field": "<string>",
"reason": "<string>",
"reasonToken": "<string>",
"reasonTokenArguments": [
{
"name": "<string>",
"value": null
}
]
}
]
}