OAuth

O endpoint OAuth fornece autenticação via OAuth 2.0 para a Catalisa Platform.

Token Endpoint

Obter Token de Acesso

POST /oauth/token

Endpoint para obter tokens de acesso usando diferentes grant types.

informação

Este endpoint é público é não requer autenticação.

Grant Types Suportados

Client Credentials

Use para autenticação servidor-a-servidor (M2M - Machine to Machine).

Request

Campo	Tipo	Obrigatório	Descrição
grant_type	string	Sim	client_credentials
client_id	string	Sim	ID da organização
client_secret	string	Sim	Secret da organização
scope	string	Não	Escopos solicitados

cURL

curl -X POST 'https://iam.stg.catalisa.app/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "550e8400-e29b-41d4-a716-446655440000",
    "client_secret": "sua-chave-secreta"
  }'

JavaScript

const response = await fetch('https://iam.stg.catalisa.app/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    grant_type: 'client_credentials',
    client_id: '550e8400-e29b-41d4-a716-446655440000',
    client_secret: 'sua-chave-secreta',
  }),
});

const tokens = await response.json();

Response (200 OK)

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJvcmdhbml6YXRpb25JZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCIsInBlcm1pc3Npb25zIjpbIklBTV9VU0VSU19DUkVBVEUiLCJJQU1fVVNFUlNfUkVBRCJdLCJ0eXBlIjoiYWNjZXNzIiwiaWF0IjoxNzA5MTIzNDU2LCJleHAiOjE3MDkxMjcwNTZ9.xxx",
  "token_type": "Bearer",
  "expires_in": 3600
}

Refresh Token

Use para renovar um access token expirado.

Request

Campo	Tipo	Obrigatório	Descrição
grant_type	string	Sim	refresh_token
refresh_token	string	Sim	Refresh token válido

cURL

curl -X POST 'https://iam.stg.catalisa.app/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

JavaScript

const response = await fetch('https://iam.stg.catalisa.app/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    grant_type: 'refresh_token',
    refresh_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  }),
});

const tokens = await response.json();

Response (200 OK)

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Estrutura do Token JWT

O access token é um JWT com a seguinte estrutura:

Header

{
  "alg": "HS256",
  "typ": "JWT"
}

Payload

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "permissions": [
    "IAM_USERS_CREATE",
    "IAM_USERS_READ",
    "CUSTOMERS_PEOPLE_CREATE"
  ],
  "type": "access",
  "iat": 1709123456,
  "exp": 1709127056
}

Campo	Descrição
sub	Subject - ID da organização ou usuário
organizationId	ID da organização (para módulos tenant-scoped)
permissions	Array de permissões concedidas
type	Tipo do token (access ou refresh)
iat	Issued At - timestamp de emissão
exp	Expiration - timestamp de expiração

Erros Possíveis

Código	Erro	Descrição
400	VALIDATION	Grant type inválido ou campos ausentes
401	UNAUTHORIZED	Client secret inválido
401	UNAUTHORIZED	Refresh token inválido ou expirado

Exemplo de Erro

{
  "code": "UNAUTHORIZED",
  "message": "Invalid client credentials",
  "statusCode": 401
}

Configurando Client Secret

Para usar o fluxo Client Credentials, a organização precisa ter um client secret configurado.

Vejá Organizações - Definir Client Secret para mais detalhes.

Boas Práticas

Dicas de Segurança

1. Nunca exponha o client_secret no frontend ou em repositórios públicos
2. Armazene tokens de forma segura (httpOnly cookies, secure storage)
3. Implemente renovação automática antes do token expirar
4. Use HTTPS em todas as comunicações
5. Rotacione secrets periodicamente em ambientes de produção

Atenção

• Access tokens expiram em 1 hora
• Refresh tokens expiram em 7 dias
• Client secrets não podem ser recuperados após criação