> This page is for Camera to Cloud.
> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://next.developer.frame.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server.
# Instruções: Gerenciar autorizações
## Visão geral
Este guia descreve os procedimentos para gerenciar tokens de autorização de dispositivos no Frame.io, incluindo atualização e revogação de tokens, além de práticas de armazenamento seguro.
## Pré-requisitos
Consulte o guia [Implementação do C2C: Configuração](./implementing-c2c-setting-up) para garantir que a configuração esteja correta.
Componentes essenciais necessários:
* Um `client_secret` válido emitido pelo Frame.io
* Seu `client_id` atribuído conforme detalhado no [guia de autenticação e autorização](./implementing-c2c-authentication-and-authorization)
* Credenciais válidas de `access_token` e `refresh_token`
## Noções básicas sobre tokens de autorização
Nosso guia anterior sobre [autenticação de dispositivos](./implementing-c2c-authentication-and-authorization) descreveu o processo de obtenção de tokens de autorização iniciais por meio da autenticação do usuário. Os tokens de acesso permanecem válidos por aproximadamente 8 horas. Para eliminar a necessidade de emparelhamento frequente de dispositivos, implementamos o escopo `offline` para obter um token de atualização juntamente com a autorização. Esse token de atualização permite a geração de novos tokens de acesso após o vencimento.
Os tokens de atualização permanecem válidos por 14 dias. Essa limitação deliberada à duração do token de acesso aumenta a segurança, minimizando possíveis vulnerabilidades decorrentes de tokens comprometidos. Observe que, se a autorização não for renovada antes do vencimento do token de atualização, será necessária uma nova autenticação do usuário.
## Processo de renovação do token de acesso
Após o vencimento do token de acesso, as solicitações de API receberão esta resposta:
```json
{
"code": 401,
"errors": [
{
"code": 401,
"detail": "You are not allowed to access that resource",
"status": 401,
"title": "Not Authorized"
}
],
"message": "Not Authorized"
}
```
Execute o seguinte comando para obter um novo token:
```shell
curl -X POST https://api.frame.io/v2/auth/token \
--header 'x-client-version: 2.0.0' \
--form 'client_id=[client_id]' \
--form 'client_secret=[client_secret]' \
--form 'grant_type=refresh_token' \
--form 'refresh_token=[refresh_token]' \
| python -m json.tool
```
A documentação detalhada para `/v2/auth/token` está disponível [aqui](/camera-to-cloud/api-reference/authentication/auth-device-token)
Esta implementação requer múltiplos fatores de autenticação para aumentar a segurança. Um terceiro não autorizado precisaria obter tanto o `refresh_token` quanto o `client_secret` para se passar com sucesso pela sua integração.
Uma renovação bem-sucedida gera esta resposta:
```json
{
"access_token": "[access_token]",
"expires_in": 28800,
"refresh_token": "[refresh_token]",
"token_type": "bearer"
}
```
Após a atualização bem-sucedida do token, suas credenciais anteriores se tornam inválidas. Certifique-se de armazenar corretamente os novos tokens de autorização.
Tentar reutilizar um token de atualização expirado resulta em:
```json
{
"error": "invalid_request"
}
```
Isso indica que o token já foi processado anteriormente e não é mais válido.
O recebimento de uma resposta `401 Not Authorized` durante a atualização do token indica a invalidação das credenciais, exigindo um novo processo de autorização.
## Lidar com respostas de falha na atualização
Devido à natureza de uso único dos valores do `refresh_token`, a falha em capturar a resposta de atualização, seja devido a interrupção na rede ou desligamento do sistema, exige reiniciar toda a sequência de autenticação/autorização.
Esse protocolo de segurança, embora possa ser inconveniente, é essencial para manter a integridade do sistema.
## Processo de revogação de token
Algumas circunstâncias podem exigir o cancelamento do acesso ao Frame.io, como a conclusão de um projeto ou a reinicialização do aplicativo. Implemente os procedimentos adequados de revogação ao cancelar a autorização atual.
Execute o seguinte comando para revogar a autorização:
Após a revogação, você deve reiniciar o processo de autenticação e autorização conforme descrito no [guia de autenticação e autorização](./implementing-c2c-authentication-and-authorization).
```shell
curl -X POST https://api.frame.io/v2/auth/revoke \
--include \
--header 'x-client-version: 2.0.0' \
--form 'client_id=[client_id]' \
--form 'client_secret=[client_secret]' \
--form 'token=[refresh_token]'
```
A documentação completa para `/v2/auth/revoke` está disponível [aqui](/camera-to-cloud/api-reference/authentication/auth-device-revoke-token)
O sistema retorna cabeçalhos sem conteúdo. O sucesso é indicado pelo código de status `200`:
```text
HTTP/2 200
...
```
Após a revogação, as operações do Frame.io que exigirem autenticação por `access_token` retornarão a mensagem `Not Authorized`. Para restaurar o acesso, é necessário emparelhar novamente o dispositivo com o projeto.
## Implementação do armazenamento de tokens
A manutenção da autorização persistente entre reinicializações do sistema requer um armazenamento seguro dos tokens. Siga estas diretrizes essenciais:
**Implemente controles de acesso do usuário:** restrinja a visibilidade e o acesso aos tokens exclusivamente aos processos do aplicativo. **Habilite a criptografia de armazenamento:** implemente criptografia para tokens armazenados, incluindo o `client_secret` e as credenciais de autorização. Nunca mantenha chaves de autorização em formato de texto simples. **Mantenha a separação de credenciais:** embora nosso aplicativo Python de demonstração consolide o armazenamento, os ambientes de produção devem separar os tokens de autorização do `client_secret`. Considere estes fatores:
* `client_secret` e `client_id` representam credenciais permanentes do dispositivo. A perda dessas credenciais resulta em falha permanente do dispositivo
* Os tokens de autorização passam por atualizações regulares durante a operação do dispositivo
* O armazenamento segregado garante que, em caso de corrupção do armazenamento de tokens, seja necessário apenas reemparelhar o dispositivo, em vez de uma redefinição completa da autenticação
Embora o SQLite ofereça recursos ideais para o armazenamento de tokens, implemente, no mínimo, um armazenamento separado para os dados de autorização e as credenciais principais.
## Próximas etapas
Parabenizamos pelo seu progresso e convidamos você a prosseguir para o guia sobre [status de conexão e heartbeats](./how-to-heartbeats-connection-info-and-status). Entre em contato com nossa equipe caso tenha alguma dúvida ou preocupação.