API Authentication

AI Tools

This document will cover the steps required to send API requests using Yoti’s new Central Auth.

Proof of Age Scope

poa:verify

All API calls will be made using an OAuth Access Token as a bearer token.

The required steps to generate this Access Token and make API calls to Yoti are as follows:

Generate a JWT token using a Yoti private key (.pem file)
Acquire an OAuth Access Token using this JWT Token
Send an API request to Yoti

A token can be reused for multiple requests - you must NOT use a new token for every request. There is a limit of 200 active tokens per service/SDK ID. We advise that you use one key for all calls within a scope and obtain a new token every 30 minutes.

Before you start

You will need a Verified Yoti Organisation account and service set up with a Private PEM key and SDK ID.

Generating a JWT Token

We use the private_key_JWT client authentication method from OIDC Core. The JWT will be signed by the RSA private key of the service/SDK ID that you are authenticating as.

Header	Value	Description
alg	PS384	Algorithm. We require the algorithm to be PS384. No other algorithms are accepted.
typ	JWT	Type. Must be the string value JWT.

The following claims must be present in the payload:

Claim	Value	Description
iss	sdk: <YOUR_SDK_ID>	Issuer. Must be set to the string “sdk:" \|\| SDK ID, e.g. sdk:67d60fe2-5576-49ae-9ac9-ad76b232c5e1.
sub	sdk: <YOUR_SDK_ID>	Subject. Must be set to the same value as iss
aud	https://api.example.com	Audience. This must be the full URL for the OAuth client credentials grant endpoint.
jti	UUID string	JWT ID. We require a valid UTF-8 string of at least 16 bytes and at most 128 bytes (not characters) in length. Each JWT that is issued must use a different jti value; the authorisation server will remember iss \|\| jti
exp	1751700000	Expiry time. The authorisation server will refuse to grant client credentials if a request is processed after this time. The expiry time can be a maximum of 30 minutes in the future.
iat	1751700000	OPTIONAL. Issued at. The authorisation server will refuse to grant client credentials if this value is unreasonably far in the past. We have a threshold of 30 minutes
nbf	1751700000	OPTIONAL. Not before. The authorisation server will refuse to grant client credentials if the request arrives before the “not before” time.

Examples

const fs = require("fs");

const jwt = require("jsonwebtoken");

const uuid = require("uuid");

const pem = fs.readFileSync("PATH_TO_PEM.pem");

const sdkId = "YOUR_SDK_ID";

const authURL = "https://auth.api.yoti.com/v1/oauth/token";

const issuedAt = Math.floor(Date.now() / 1000);

const expiry = issuedAt + 30 * 60;

function buildJWT() {

const claims = {

iss: "sdk:" + sdkId,

sub: "sdk:" + sdkId,

aud: authURL,

jti: uuid.v4(),

exp: expiry,

iat: issuedAt,

};

const headers = {

alg: "PS384",

typ: "JWT",

};

try {

const token = jwt.sign(claims, pem, {

algorithm: "PS384",

using System;

using System.IO;

using System.IdentityModel.Tokens.Jwt;

using System.Security.Claims;

using Microsoft.IdentityModel.Tokens;

using System.Security.Cryptography;

using System.Text;

class Program

{

static void Main()

{

string pemPath = "PATH_TO_PEM.pem";

string sdkId = "YOUR_SDK_ID";

string authURL = "https://auth.api.yoti.com/v1/oauth/token";

string token = BuildJWT(pemPath, sdkId, authURL);

Console.WriteLine("Generated JWT: " + token);

}

static string BuildJWT(string pemPath, string sdkId, string authURL)

{

// Read PEM private key

string pem = File.ReadAllText(pemPath);

var rsa = RSA.Create();

rsa.ImportFromPem(pem.ToCharArray());

var securityKey = new RsaSecurityKey(rsa);

package main

import (

"crypto"

"crypto/rand"

"crypto/rsa"

"crypto/x509"

"encoding/base64"

"encoding/json"

"encoding/pem"

"fmt"

"log"

"os"

"time"

"github.com/google/uuid"

)

func main() {

sdkID := "YOUR_SDK_ID"

pemPath := "PATH_TO_PEM.pem"

authURL := "https://auth.api.yoti.com/v1/oauth/token"

token, err := buildJWT(pemPath, sdkID, authURL)

if err != nil {

log.Fatal("Error building JWT:", err)

}

fmt.Println("Generated JWT successfully")

fmt.Println(token)

}

// buildJWT creates a PS384-signed JWT to use as the client assertion in the OAuth2

// client_credentials request.

func buildJWT(pemPath, sdkID, authURL string) (string, error) {

<?php

require_once __DIR__ . '/vendor/autoload.php';

$pemPath = 'PATH_TO_PEM.pem';

$sdkId = 'YOUR_SDK_ID';

$authURL = 'https://auth.api.yoti.com/v1/oauth/token';

$token = buildJWT($pemPath, $sdkId, $authURL);

echo "Generated JWT: " . $token . "\n";

function buildJWT(string $pemPath, string $sdkId, string $authURL): string

{

$pem = file_get_contents($pemPath);

$now = time();

$header = json_encode(['alg' => 'PS384', 'typ' => 'JWT']);

$claims = json_encode([

'iss' => 'sdk:' . $sdkId,

'sub' => 'sdk:' . $sdkId,

'aud' => $authURL,

'jti' => bin2hex(random_bytes(16)),

'iat' => $now,

'exp' => $now + 300,

]);

$signingInput = base64UrlEncode($header) . '.' . base64UrlEncode($claims);

package com.example;

import java.math.BigInteger;

import java.nio.file.Files;

import java.nio.file.Path;

import java.security.KeyFactory;

import java.security.Signature;

import java.security.interfaces.RSAPrivateKey;

import java.security.spec.MGF1ParameterSpec;

import java.security.spec.PSSParameterSpec;

import java.security.spec.RSAPrivateCrtKeySpec;

import java.util.Base64;

import java.util.UUID;

public class JwtSnippet {…}

Response

eyJhbGciOiJQUzM4NCIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzZGs6OWVlM2RiNmUtM2UwYy00ZTg1LWIyYTMtOTliZTMxNmY5MDJhIiwic3ViIjoic2RrOjllZTNkYjZlLTNlMGMtNGU4NS1iMmEzLTk5YmUzMTZmOTAyYSIsImF1ZCI6Imh0dHBzOi8vYXV0aC5hcGkueW90aS5jb20vdjEvb2F1dGhvdG9rZW4iLCJqdGkiOiI2N2RlMjM0OC0xOWYyLTRmODctOWE4YS01YTEzZjM5ZWIyNTEiLCJleHAiOjE3NzA3Mjc3MjAsImlhdCI6MTc3MDcyNTkyMH0.lgCJJ57OeV_mJGw91DR71ZRHgOWLbzSK1PYhqC59333PB4fBzxcz4chWHo5Go7vL_vGNYpJQJI-UuuBbZNNCF5OuDnWSQNHIcB_QW7OsYa6al8PcbC21oZrbdBSTbJdk_7S7ARo5noXKf4tH_cnbUkL7I50lMPnJngZBfpLb6ATAjbSWhsKhrT--GlWKs-NB58z8V-PDmG6c93PF7krA6oB964OtIMEHtFiXfbQB61xiYOUyR94G-pLUbftDnvXhyxmT_MZXaZRSIfIy8l75scBoHv96ylSH1yqBcw5vdQoye-Cd6YXGlJLS5QM9fqFm9JYIeOh7DP7Vo4PRTIFlcQ

OAuth Token Grant

Once you have generated a JWT token, you can use it to request an OAuth Access Token for Yoti API calls.

You must request this from the Yoti authorisation server. The request method is POST, and the body from the client must be encoded with the application/x-www-form-urlencoded content type

POST https://auth.api.yoti.com/v1/oauth/token

The request must include the following form values:

Header	Value	Description
grant_type	client_credentials	OAuth grant type
scope	<your_scope> - string	A space-separated list of one or more scopes that the token will grant access for.
client_assertion_type	urn:ietf:params:oauth:client-assertion-type:jwt-bearer	The OAuth client assertion type
client_assertion	JWT value	The value of the JWT token
comment	“production_key”	Must be valid UTF-8, limited to 128 characters, and comprise only Unicode printable characters.

Examples

const axios = require("axios");

const token = "YOUR_JWT_TOKEN"

async function requestOAuthToken() {

const formData = new URLSearchParams({

grant_type: "client_credentials",

scope: "your_scope_here",

client_assertion_type:

"urn:ietf:params:oauth:client-assertion-type:jwt-bearer",

client_assertion: token,

});

try {

axios

.post("https://auth.api.yoti.com/v1/oauth/token", formData, {

headers: {

"Content-Type": "application/x-www-form-urlencoded",

})

.then((response) => {

console.log("OAuth token response:", response.data);

});

} catch (error) {

console.error("Error requesting OAuth token:", error);

using System;

using System.Net.Http;

using System.Threading.Tasks;

class Program

{

static async Task Main()

{

string token = "YOUR_JWT_TOKEN"

var formData = new FormUrlEncodedContent(new[]

{

new KeyValuePair<string, string>("grant_type", "client_credentials"),

new KeyValuePair<string, string>("scope", "your_scope_here"),

new KeyValuePair<string, string>("client_assertion_type", "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"),

new KeyValuePair<string, string>("client_assertion", token)

});

using var httpClient = new HttpClient();

try

{

var response = await httpClient.PostAsync("https://auth.api.yoti.com/v1/oauth/token", formData);

package main

import (

"fmt"

"io"

"log"

"net/http"

"net/url"

)

func main() {

token := "YOUR_JWT_TOKEN"

authURL := "https://auth.api.yoti.com/v1/oauth/token"

formData := url.Values{

"grant_type": {"client_credentials"},

"scope": {"your_scope_here"},

"client_assertion_type": {"urn:ietf:params:oauth:client-assertion-type:jwt-bearer"},

"client_assertion": {token},

}

resp, err := http.PostForm(authURL, formData)

if err != nil {

log.Fatal("Error requesting OAuth token:", err)

}

defer resp.Body.Close()

body, _ := io.ReadAll(resp.Body)

fmt.Println("OAuth token response:", string(body))

<?php

$token = 'YOUR_JWT_TOKEN';

$formData = http_build_query([

'grant_type' => 'client_credentials',

'scope' => 'your_scope_here',

'client_assertion_type' => 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',

'client_assertion' => $token,

]);

$context = stream_context_create([

'http' => [

'method' => 'POST',

'header' => 'Content-Type: application/x-www-form-urlencoded',

'content' => $formData,

]);

$response = file_get_contents('https://auth.api.yoti.com/v1/oauth/token', false, $context);

echo "Response: " . $response . "\n";

package com.example;

import java.net.URI;

import java.net.URLEncoder;

import java.net.http.HttpClient;

import java.net.http.HttpRequest;

import java.net.http.HttpResponse;

import java.nio.charset.StandardCharsets;

public class OauthSnippet {

public static void main(String[] args) throws Exception {

String token = "YOUR_JWT_TOKEN";

String authURL = "https://auth.api.yoti.com/v1/oauth/token";

String formData = "grant_type=client_credentials"

+ "&scope=" + encode("your_scope_here")

+ "&client_assertion_type=" + encode("urn:ietf:params:oauth:client-assertion-type:jwt-bearer")

+ "&client_assertion=" + encode(token);

HttpRequest request = HttpRequest.newBuilder()

Response

{

access_token: 'yta_NZuDqGkNOFp4DgwYbdR4TY_X15IEZsuWArACxprJJwp93MCG',

token_type: 'bearer',

expires_in: 2700,

scope: 'your-scope-here'

}

Errors

Due to the OAuth RFC, we will only return 400 or 403 error codes. Details of the error will be found in the response.

Error Code	Details
400	Bad Request
403	Forbidden

{

"error": 'invalid_scope',

"error_description": 'empty list or unrecognised scope name'

}

SDKs

Methods have been added to the Yoti SDKs to generate the Access Tokens instead of the steps above.

use Yoti\Auth\AuthenticationTokenGenerator;

$generator = AuthenticationTokenGenerator::builder()

->withSdkId('YOUR_SDK_ID')

->withPemFilePath('PATH_TO_YOUR_PEM')

->build();

$response = $generator->generate(['your_scope_here']); // must specify the scope here

coming soon

import com.yoti.auth.AuthenticationTokenGenerator;

import com.yoti.auth.CreateAuthenticationTokenResponse;

import com.yoti.api.client.FileKeyPairSource;

import java.io.File;

import java.util.Collections;

AuthenticationTokenGenerator generator = AuthenticationTokenGenerator.builder()

.withSdkId("YOUR_SDK_ID")

.withKeyPairSource(FileKeyPairSource.fromFile(new File("PATH_TO_YOUR_PEM")))

.build();

CreateAuthenticationTokenResponse response = generator.generate(Collections.singletonList("poa:verify"));

String token = response.getAccessToken();

coming soon

Last updated on

Was this page helpful?