Autenticação

Ainda não tem credenciais? Veja como pedir acesso em Solicitação de acesso.

As APIs usam OAuth 2.0 com o fluxo client credentials. Em resumo:

Você troca o client_id e o client_secret por um token de acesso.
Envia o token no header Authorization de cada chamada às APIs de negócio.
Renova o token antes de ele expirar.

1. Obter o token

Faça POST em https://apim-oslodtvm-dev.azure-api.net/auth/v1/token, com o corpo em application/x-www-form-urlencoded:

Campo	Descrição
`grant_type`	Sempre `client_credentials`.
`client_id`	Identificador do parceiro, entregue no cadastro.
`client_secret`	Segredo do parceiro, entregue no cadastro. Não o compartilhe nem o registre em logs.
`scope`	A API desejada, no formato `api://<identificador-da-api>/.default`.

Esta rota não exige o header Ocp-Apim-Subscription-Key.

curl -X POST "https://apim-oslodtvm-dev.azure-api.net/auth/v1/token" -H "Content-Type: application/x-www-form-urlencoded" --data-urlencode "grant_type=client_credentials" --data-urlencode "client_id=00000000-0000-0000-0000-000000000000" --data-urlencode "client_secret=segredo-ficticio-nao-use" --data-urlencode "scope=api://09e65fcd-2eca-4a10-9b84-0fda9e4cf790/.default"

{
"token_type": "Bearer",
"expires_in": 3599,
"access_token": "token-ficticio"
}

O scope identifica a API

Cada API tem um identificador próprio, e o scope indica para qual delas o token será usado. Um token vale para uma única API: para chamar Workflow e Cadastro, solicite um token para cada uma.

API	scope
Workflow	`api://09e65fcd-2eca-4a10-9b84-0fda9e4cf790/.default`
Cadastro	`api://13797b3b-f174-4cb2-b982-7224d3c975bb/.default`

Se o seu cadastro não der acesso à API pedida, a rota de token responde 400. Os erros dessa rota seguem o formato OAuth 2.0, descrito em Erros.

2. Validade e renovação

O token vale cerca de 1 hora, mas não assuma uma duração fixa. Renove-o pela claim exp, que indica o instante de expiração, solicitando um novo token antes desse momento. O campo expires_in da resposta também informa a validade, em segundos.

3. Chamar as APIs de negócio

Envie o token no header Authorization, no formato Bearer. As APIs de negócio exigem também o header Ocp-Apim-Subscription-Key, com a chave de assinatura do parceiro.

Header	Valor
`Authorization`	`Bearer <token>`
`Ocp-Apim-Subscription-Key`	Chave de assinatura do parceiro. Veja Solicitação de acesso.

curl "https://apim-oslodtvm-dev.azure-api.net/workflow/v1/tasks/a1b2c3d4" -H "Authorization: Bearer token-ficticio" -H "Ocp-Apim-Subscription-Key: chave-ficticia"

Funções (permissões)

Além de um token válido, cada operação exige uma função associada ao parceiro. Sem a função, a API responde 403.

Função	API	Operação
`Workflow.Read`	Workflow	Consultar tarefa (`GET /tasks/{taskId}`)
`Workflow.Write`	Workflow	Criar tarefa (`POST /tasks`)
`Cadastro.Read`	Cadastro	Consultar cliente (`GET /clients/{cnpj}`)

Para solicitar uma API ou uma função adicional, veja Solicitação de acesso.

Boas práticas

Guarde o client_secret em local seguro e nunca o inclua em código-fonte, logs ou aplicações executadas no dispositivo do usuário.
Reaproveite o token enquanto for válido, em vez de pedir um novo a cada chamada: a rota de token também tem limite de chamadas.
Em 401, solicite um novo token e repita a chamada. Em 403, o token é válido, mas falta a função da operação.