Token de acesso¶

Realiza a troca do código de autorização pelo token de acesso que autoriza a realização das chamadas de serviço para utilização do certificado digital do usuário.

`POST /token`¶

Solicitação¶

A aplicação deve solicitar ao endpoint de token do PSC SerproID, https://serproid.serpro.gov.br/oauth/v0/oauth/token postando via application/x-www-form-urlencoded os parâmetros necessários.

Parâmetros¶

A tabela a seguir descreve os parâmetros suportados pelo endpoint de token do PSC SerproID.

Parâmetro	Presença	Descrição / Valor
`grant_type`	(Obrigatório)	O valor deve ser "`authorization_code`"
`client_id`	(Obrigatório)	Deve conter o `client_id` (identificador único) da aplicação
`client_secret`	(Obrigatório)	Deve conter a `client_secret` (senha) da aplicação, utilizado em conjunto com o `client_id` para a sua identificação
`code`	(Obrigatório)	Deve conter o código de autorização, `code`, retornado na `redirect_uri` no serviço código de autorização
`code_verifier`	(Obrigatório)	Deve ser informado a chave de prova aleatória (`code_verifier`) gerada para derivar o desafio (`code_challenge`) informado na solicitação de autorização. Para mais informações, consulte PKCE RFC. Visualize aqui o código de exemplo
`redirect_uri`	(Opcional)	Caso tenha sido informado na solicitação de autorização, o mesmo valor deve ser informado

Exemplo¶

O exemplo encontra-se com quebras de linha e espaços para melhor leitura

HTTPcURL

POST /oauth/v0/oauth/token HTTP/1.1
Host: serproid.serpro.gov.br
Content-type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id={client_id}
&client_secret={client_secret}
&code={código_de_autorização}
&code_verifier={code_verifier}
&redirect_uri={redirect_uri}

curl -X POST \
https://serproid.serpro.gov.br/oauth/v0/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'cache-control: no-cache' \
-d 'grant_type=authorization_code&client_id={client_id}&client_secret={client_secret}&code={código_de_autorização}&code_verifier={code_verifier}&redirect_uri={redirect_uri}'

Resposta da solicitação¶

O PSC SerproID irá verificar todos os parâmetros para validar a solicitação. As credenciais da aplicação, client_id e client_secret, serão checadas para realizar a sua autenticação, será verificado se o code informado não está expirado e se foi emitido para a aplicação identificada, será checado se o valor do code_verifier foi utilizado para derivar o code_challenge apresentado na solicitação de autorização, assim como, se informado, será verificado se a redirect_uri é idêntica à apresentada na solicitação de autorização.

Solicitação válida (Sucesso)¶

Se a solicitação estiver válida, o PSC SerproID irá gerar um token de acesso (access_token), que será retornado via HTTP code 200 na resposta da solicitação em conjunto com alguns parâmetros adicionais no formato application/json.

Atenção

O token retornado concede permissão à utilização dos serviços relacionados à utilização do certificado digital do usuário, como o uso da chave privada para a realização de assinatura digital, considerações de segurança devem ser garantidas pela aplicação para que o seu valor não seja exposto.

Parâmetros¶

JSON:

access_token - (string) - token de acesso gerado pelo PSC SerproID que permite a chamada aos serviços de utilização do certificado
token_type- (string) - tipo do token, valor fixo "Bearer"
expires_in - (inteiro) - validade do token em segundos
scope - (string) - escopo de autorização concedido conforme permissão de uso solicitada pela aplicação
authorized_identification_type - (string) - identifica se o certificado autorizado é do tipo Pessoa Física ou Pessoa Jurídica, "CPF" ou "CNPJ", respectivamente
authorized_identification - (string) - valor do "CPF" ou "CNPJ" do certificado autorizado, dependendo do valor informado no campo authorized_identification_type

A validade do token de acesso dependerá do tipo de permissão de uso solicitada através do parâmetro scope na solicitação de autorização. Para os valores single_signature, multi_signature e authentication_session, o token estará válido por 5 minutos. Para o valor signature_session, o token está válido pelo período de tempo autorizado pelo titular do certificado.

Saiba mais

Os períodos de tempo possíveis para autorização do titular do certificado, quando da solicitação de permissão de escopo de sessão de assinatura (valor signature_session informado no parâmetro scope) variam de acordo com o tipo de certificado.

Certificado de Pessoa Física: 15 Minutos, 1 hora, 4 horas, 8 horas, 1 dia, 3 dias, 7 dias

Certificado de Pessoa Juríddica: 1 hora, 8 horas, 1 dia, 3 dias, 7 dias, 15 dias, 30 dias

Exemplo¶

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: Cache-Control
Pragma: no-cache

{
    "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJuZW9pZCIsImF1ZCI6Im5lb2lkIiwic3ViIjoiNjRlNTg3ZmEtNGYzMC00ODdkLTk2ZjAtNDRlNmIxNGZmNjIwIiwiaWF0IjoxNTI4OTgyMDYyLCJqdGkiOiI4N2NhYTkzOS0wMjgxLTQ1YjktODA3Mi1lNjI1NDkzN2JlMzYiLCJoYXQiOiJNVEV6T1RJQUFBQUFBQUFBQUFBQUFPYXBWdEJnenp0b2JxZFY5Sk5CemRCVVVQcHlhdGtMWTJ2UjNDTFJmQy8wQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBRC8vLy8vLy8vLy93PT0ifQ.qsUtA4hBWGtM5HYuMcLMtWtDQtdgk95Rf_sJhMbAgvEqkq0xq6e4-1QXrLfodbbOES0Jnz4RpRpdmuXOVcLcduCmstgOfPIvjqi5Ewb93zTpuGavDGCmNiFpd33T8ytdl9KhIyCVisDg8LEWIdiPscBk421zTu2Dquj4rzQGVVM1EkrCqOazeU6zxnF3gSuIOgnvxeReu6k-runIPr5F1ZAsglPsQKp-WZqmqG9gmzoNOSXSFFD3g2S5nS4zdKuOL8NH1QfJytF72Ylvifhj4Fdlz9wWLDXZwMmvQjhHmJetNnN16D1CS3PUlQq1VdStMktgoOSqQOLzUMxPuLq-gw",
    "token_type": "Bearer",
    "expires_in": 300,
    "scope": "single_signature",
    "authorized_identification_type": "CPF",
    "authorized_identification": "11111111111"
}

Solicitação inválida (Erro)¶

Se a solicitação for considerada inválida, seja devido a verificação dos parâmetros informados ou caso algum erro inesperado aconteça, o PSC SerproID retornará um erro no formato application/json com o HTTP code correspondente ao tipo do erro.

Parâmetros¶

JSON:

error - (string) - tipo do erro
error_description- (string) - descrição do erro
error_uri - (string) - URI da documentação que descreve o erro

Exemplo¶

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
    "error": "invalid_request",
    "error_description": "Parâmetro(s) requerido(s) não informado(s): code_verifier",
    "error_uri": "https://servicos.serpro.gov.br/serproid/docs/#lista-de-erros-possiveis"
}

Lista de erros¶

Tipo do erro	*HTTP Code*	Detalhes
`invalid_request`	400	A estrutura da solicitação encontra-se inválida. Cenários possíveis: Parâmetro requerido não informado Parâmetro com mais de um valor informado
`unsupported_grant_type`	400	Valor do parâmetro `grant_type` inválido
`invalid_client`	401	Credenciais de autenticação inválidas. Cenários possíveis: Não foi possível identificar a aplicação pela `client_id` `client_secret` informada inválida para a aplicação identificada
`invalid_grant`	400	O valor dos parâmetros `code`, `code_verifier` ou `redirect_uri` são inválidos. Cenários possíveis: Valor inválido do código de autorização (`code`) Código de autorização (`code`) expirado Valor do parâmetro `redirect_uri` com encode inválido Valor do parâmetro `redirect_uri` não informado ou diferente do apresentado na solicitação de autorização Valor do parâmetro `code_verifier` não condiz com o valor do `code_challenge` informado na solicitação de autorização O token de acesso (`access_token`) referente ao código de autorização (`code`) informado já foi gerado e/ou utilizado
`server_error`	500	Algo inesperado aconteceu e não foi possível dar prosseguimento com a solicitação

Token de acesso¶

POST /token¶

Solicitação¶

Parâmetros¶

Exemplo¶

Resposta da solicitação¶

Solicitação válida (Sucesso)¶

Parâmetros¶

Exemplo¶

Solicitação inválida (Erro)¶

Parâmetros¶

Exemplo¶

Lista de erros¶

`POST /token`¶