A documentação completa da API CPASS está disponível em [https://api.cpasstech.com.br/docs/](https://api.cpasstech.com.br/docs/). Implementamos o padrão OAuth 2.0 que é descrito pela [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.3). ## Credenciais Uma vez que a parceria HBO e CPASS for concretizada, iremos cadastrar a HBO como um OAuth Client em nossa plataforma CPASS e iremos fornecer as seguintes credenciais: `client_id: <token>` `client_secret: <token>` ## O Fluxo Considere a seguinte URI como base: `BASE_URI` = `api.cpasstech.com.br` #### Autorização Dado que o usuário irá acessar o conteúdo da HBO através da Call to Action "Connect Your Service Provider" e irá optar por conectar-se via CPASS. A HBO irá redirecionar o usuário para a seguinte URL: ``` GET /oauth/autorize/?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri> Host <BASE_URL> ``` Onde: * `client_id` deverá ser substituido pelo `client_id` citado na seção "Credenciais" * `redirect_uri` deverá ser substituido pela uri para a qual o usuário será redirecionado uma vez que esse completa sua interação com a CPASS. Iremos solicitar as uris válidas a HBO no momento que cadastrarmos essa como um OAuth Client, descrito na seção "Credenciais". Uma vez na plataforma CPASS, o usuário deverá realizar login com email e senha e autorizar a HBO, OAuth Client, a acessar seus recursos na CPASS. Nesse passo, além de verificar a validade do email e senha, também verificamos se o usuário está apto a utilizar o serviço da HBO na data vigente. Caso esse processo ocorra com sucesso, ou seja, o usuário é valido e está apto para acessar a HBO. A plataforma CPASS irá redirecionar o usuário de volta para a HBO, `redirect_uri` informada no passo acima, enviando junto a query-string `code` com o código a ser utilizado no próximo passo: ``` HTTP/1.1 302 Found Location: <redirect_uri>?code=SplxlOBeZQQYbYS6WxSbIA ``` Caso ocorra algum erro no passo acima ou o usuário venha a não autorizar o acesso da HBO a CPASS. A seguinte resposta será retornada: ``` HTTP/1.1 302 Found Location: <redirect_uri>?error=access_denied ``` A query-string `error` pode conter os seguintes valores: * `invalid_request` Há algum parametro obrigatório que esteja ausente na request. * `access_denied` O usuário negou o acesso da HBO a plataforma CPASS. * `server_error` Houve algum erro não esperado do lado da CPASS e a interação não pode ser finalizada. #### Solicitação de Token de Acesso Dado que o usuário tenha finalizado o passo acima, "Autorização", com sucesso, a HBO deverá solicitar um token de acesso com o código retornado no final do processo de autorização. ``` POST /oauth/token HTTP/1.1 Host: <BASE_URI> Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=<code>&redirect_uri=<redirect_uri>&client_id=<client_id>&client_secret=<client_secret> ``` Não se esqueça de subsituir: * `code` com o código retornado no passo anterior * `redirect_uri` com a uri cadastrada cadastrada previamente em "Credenciais" * `client_id` ID cadastrado previamente em "Credenciais" * `client_secret` Secret cadastrado previamente em "Credenciais" Uma vez que essa request tenha sido realizada com sucesso, a seguinte respostá será retornada: ``` HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "access_token": "2YotnFZFEjr1zCsicMWpAA", "token_type": "Bearer", "expires_in": 3600, "scope": "red", "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA" } ``` #### Revogação de Token de Acesso (logout) Caso seja necessário revogar o token de acesso (logout), é possível fazer isso através do endpoint abaixo: ``` POST /oauth/revoke-token HTTP/1.1 Host: <BASE_URI> Content-Type: application/x-www-form-urlencoded token=<token>&client_id=<client_id>&client_secret=<client_secret> ``` Substitua: * `token` Token de acesso a ser revogado. * `client_id` ID cadastrado previamente em "Credenciais" * `client_secret` Secret cadastrado previamente em "Credenciais" Uma vez que essa request tenha sido realizada com sucesso, a seguinte respostá será retornada: ``` HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded Cache-Control: no-store Pragma: no-cache ``` #### Obter informações especificas de cada usuário É possível obter informações especificas de cada cliente, tais como dados pessoais bem como é possível em um futuro retornar dados de acesso tais como, tipo de tela que o cliente estã usando, quantidade de acessos simultaneos etc. ``` GET /oauth/userinfo HTTP/1.1 Host: <BASE_URI> Authorization: Bearer <access_token> Content-Type: application/json;charset=UTF-8 ``` Uma vez que essa request tenha sido realizada com sucesso, a seguinte respostá será retornada: ``` HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32", "birthdate": "1982-03-10", "email": "richard@pipedpuper.com", "email_verified": true, "family_name": "Hendricks", "given_name": "Richard", "phone_number": "555-555-5555", "picture": "http://www.piedpiper.com/app/themes/pied-piper/dist/images/photo-richard.png", "plans": [ "name": "Plan Name", "image": "Product image", "duration": [ "started_at": "15-05-2020", "ended_at": "17-05-2020" ] ] } ``` #### Gerenciamento de aplicações Inicialmente não iremos expor endpoints para registro de novas aplicações bem como para alteração ou exclusão, todo esse gerenciamento sera feito internamente pelo time da CPASS.