Autenticação

Todos os pedidos à API são autenticados através de um Token de Serviço — um Bearer token de curta duração obtido via o grant OAuth2 Client Credentials. Trata-se de um fluxo máquina a máquina: não existe qualquer login humano envolvido.

Como funciona

A sua integração dispõe de um client_id e de um client_secret (fornecidos pelo seu gestor de conta DokStamp). Troque-os por um token de acesso e inclua esse token em cada pedido à API.

client_id + client_secret
        │
        ▼
POST /oauth/token
        │
        ▼
access_token (válido 12h)
        │
        ▼
Authorization: Bearer {access_token}

1. Obtenha um token

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

curl -X POST https://api.dokstamp.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

const res = await fetch('https://api.dokstamp.com/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: process.env.DOKSTAMP_CLIENT_ID,
    client_secret: process.env.DOKSTAMP_CLIENT_SECRET,
  }),
});
const { access_token, expires_in } = await res.json();

$response = Http::asForm()->post('https://api.dokstamp.com/oauth/token', [
    'grant_type'    => 'client_credentials',
    'client_id'     => env('DOKSTAMP_CLIENT_ID'),
    'client_secret' => env('DOKSTAMP_CLIENT_SECRET'),
]);
$token = $response->json('access_token');

Resposta:

{
  "token_type": "Bearer",
  "expires_in": 43200,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."
}

Campo	Descrição
`access_token`	Incluir em cada pedido à API via `Authorization: Bearer`
`expires_in`	Validade em segundos — 43 200 = 12 horas

2. Utilize o token

Inclua o token em cada pedido subsequente:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
Accept: application/json
X-Tenant: your-tenant-identifier

3. Renovação do token

Os tokens expiram após 12 horas. Não existe refresh token — solicite um novo com as suas credenciais quando necessário. Padrão recomendado: guarde o token em cache e renove-o proativamente ~60 segundos antes da expiração.

let token = null;
let expiresAt = null;

async function getToken() {
  if (token && Date.now() < expiresAt - 60_000) return token;

  const res = await fetch('https://api.dokstamp.com/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: process.env.DOKSTAMP_CLIENT_ID,
      client_secret: process.env.DOKSTAMP_CLIENT_SECRET,
    }),
  });

  const data = await res.json();
  token = data.access_token;
  expiresAt = Date.now() + data.expires_in * 1000;
  return token;
}

Endpoints públicos

Estes endpoints não requerem autenticação:

Endpoint	Finalidade
`POST /oauth/token`	Obter um token de serviço
`GET /files/{uuid}/download`	Transferir um documento assinado

Guarde client_id e client_secret em variáveis de ambiente ou num gestor de segredos. Nunca os inclua diretamente no código-fonte.

Primeiros Passos

Conceitos Fundamentais

Autenticação

Instituições

Organizações

Cursos

Módulos

Estudantes

Matrículas

Certificados

Modelos de Certificado

Ficheiros

Guias

Guia de Integração

Autenticação

Autenticação

Como funciona

1. Obtenha um token

2. Utilize o token

3. Renovação do token

Endpoints públicos

​Autenticação

​Como funciona

​1. Obtenha um token

​2. Utilize o token

​3. Renovação do token

​Endpoints públicos

Autenticação

Como funciona

1. Obtenha um token

2. Utilize o token

3. Renovação do token

Endpoints públicos