Visão Geral

A Public API usa OAuth 2.0 Authorization Code com PKCE. Esse fluxo é indicado para integrações em que o usuário autoriza uma aplicação externa a acessar dados da Soft CS em nome dele.

Fluxo Resumido

1. A aplicação externa gera um code_verifier e um code_challenge
2. A aplicação redireciona o usuário para a Soft CS
3. O usuário faz login, se necessário, e permite o acesso
4. A Soft CS redireciona de volta para o redirect_uri com um code
5. A aplicação troca o code por access_token
6. A aplicação usa o access_token para chamar a Public API
7. Se autorizado com offline_access, a aplicação usa refresh_token para renovar acesso

1. Gerar PKCE

Antes de iniciar o fluxo, gere um code_verifier.

Requisitos recomendados:

• Tamanho: 43 a 128 caracteres
• Caracteres: A-Z, a-z, 0-9, "-", ".", "_", "~"

Depois gere o code_challenge:

code_challenge = BASE64URL(SHA256(code_verifier))

Use sempre: code_challenge_method=S256

2. Iniciar Autorização

Redirecione o usuário para:

GET /api/public/v1/oauth/authorize

Parâmetros:

Exemplo:

GET /api/public/v1/oauth/authorize?client_id=softcs-public-api-local-test&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&response_type=code&scope=openid+profile+email+offline_access+clients%3Aread&state=abc123&nonce=xyz789&code_challenge=<code_challenge>&code_challenge_method=S256

3. Usuário Permite Acesso

A Soft CS pode pedir login se o usuário ainda não estiver autenticado.

Depois, o usuário verá uma tela informando:

• Qual aplicação está solicitando acesso
• Qual conta Soft CS está conectada
• Quais permissões serão liberadas

Se o usuário permitir, o fluxo continua.

4. Receber Code No Callback

Após a autorização, a Soft CS redireciona para o redirect_uri informado.

Exemplo:

https://example.com/callback?code=<authorization_code>&state=abc123

⚠️ Importante: Valide o state recebido. Ele deve ser igual ao state enviado no passo de autorização.

5. Trocar Code Por Tokens

Faça uma requisição server-to-server:

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

Parâmetros do Body:

Exemplo:

curl -X POST "https://app.softcs.com.br/api/public/v1/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=<client_id>" \
  --data-urlencode "code=<authorization_code>" \
  --data-urlencode "redirect_uri=https://example.com/callback" \
  --data-urlencode "code_verifier=<code_verifier>"

Resposta:

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "...",
  "scope": "openid profile email offline_access clients:read"
}

6. Chamar A Public API

Use o access_token no header Authorization.

GET /api/public/v1/clients
Authorization: Bearer <access_token>

Exemplo:

curl "https://app.softcs.com.br/api/public/v1/clients" \
  -H "Authorization: Bearer <access_token>"

Possíveis respostas:

• ✅ Se o token for válido e tiver o escopo necessário, a API responde normalmente
• ❌ Se faltar escopo, a API retorna 403
• ❌ Se o token estiver ausente, inválido ou expirado, retorna 401

7. Renovar Token Com Refresh Token

Se o usuário autorizou offline_access, a resposta pode incluir refresh_token.

Para renovar:

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

Parâmetros do Body:

Exemplo:

curl -X POST "https://app.softcs.com.br/api/public/v1/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=<client_id>" \
  --data-urlencode "refresh_token=<refresh_token>"

Resposta:

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "...",
  "scope": "openid profile email offline_access clients:read"
}

8. Revogar Token

Para encerrar o acesso de um token:

POST /api/public/v1/oauth/revoke
Content-Type: application/x-www-form-urlencoded

Parâmetros do Body:

Exemplo:

curl -X POST "https://app.softcs.com.br/api/public/v1/oauth/revoke" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "token=<token>" \
  --data-urlencode "token_type_hint=refresh_token"

Resumo Dos Endpoints