Authentication Using Access Token
- Sandesh Melkote Shivashankar
- Antti Peltosaari (Unlicensed)
- Garrick Lam (Unlicensed)
These guidelines have been deprecated in favor of Oauth 2.0 based authentication
This document describes the process of obtaining access token and refresh token and use that token to access Amino APIs.
How to obtain Access Token:
There are different ways to obtain access token:
Access Token from oauth endpoint:
Send request to caiway/delta OAuth server:
|
Response :
|
Client can call "/api/oauth/login_with_token" endpoint to obtain access_token
It accepts a form-encoded POST variable named "access_token" which contains the token.
Example curl
curl -X POST \ http://server.local/api/oauth/login_with_token \ -H 'cache-control: no-cache' \ -H 'content-type: application/x-www-form-urlencoded' \ -d access_token=3efb85fa-905a-4cbe-9495-f15221fbff96 \ -d service=<service user name>
Access Token using User ID:
- User authentication is possible using the access token.To do so, client should first use the login end point to obtain the access token. See Login and authentication#/User%20Authentication/loginUser
- Once successfully authenticated, login end point provides access token and refresh token.
- Special case: If some users are already logged in by cookie, for such cases access tokens can be obtained by cookie <-> token exchange process, See https://confluence.aminocom.com/display/MAPI/Cookie-token+exchange for the exchange process.
An example response from login end point after successful login:
{
"userStat": {
"maxAllowedSession": 1000,
"currentSession": 1,
"migrated": false,
"configuration": 1,
"emailSubscription": {
"all": "email"
},
"premiumUser": false,
"streamingOver3G": true,
"accessToken": [
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjb20uYW1pbm9jb20iLCJhdWQiOiJjb20uYW1pbm9jb20iLCJ0eXBlIjoiYWNjZXNzIiwianRpIjoiNDFRazVpSzMzRyIsImlhdCI6MTU2MDQ0NTE0MiwibmJmIjoxNTYwNDQ1MTQyLCJleHAiOjE1NjA0NDg3NDIsImRhdGEiOnsidXNlcklkIjoiMiIsInVzZXJfZW1haWwiOiJhdXRoX3VzZXJAZW1haWwuY29tIn0sInN1YiI6IjIifQ.Ij5sAjR-hLeT9TPJHqDNe1nGQS_2iFBNYT5NWWWoP74",
1560448742
],
"refreshToken": [
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjb20uYW1pbm9jb20iLCJhdWQiOiJjb20uYW1pbm9jb20iLCJ0eXBlIjoicmVmcmVzaCIsImp0aSI6Ik5GaGhRSno4QlgiLCJpYXQiOjE1NjA0NDUxNDIsIm5iZiI6MTU2MDQ0NTE0MiwiZXhwIjoxNTYzMDM3MTQyLCJkYXRhIjp7InVzZXJJZCI6IjIiLCJ1c2VyX2VtYWlsIjoiYXV0aF91c2VyQGVtYWlsLmNvbSJ9LCJzdWIiOiIyIn0.7NNRoYHWuLpBh6MOVFsMO-dIi-zyfCinqWR1ytuadac",
1563037142
]
}
}
The timestamp value in the Access token and Refresh token array is the expiration time for the respective tokens.
Access token using username/password
Authentication and receiving access token using username and password is available through sending POST request to /api/auth/v1/access_tokens endpoint.
Example request:
curl --location --request POST 'http://sam-booxdemo.aminocom.com/api/auth/v1/access_tokens' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-raw '{
"grant_type": "password",
"credentials": {
"username": "someuser@24i.com",
"password": "qwerty123"
}
}'
Example response:
{
"data": {
"type": "AuthenticationTokens",
"id": "4f3d8946-4423-11ea-bbb8-b7af30354b4a",
"attributes": {
"login_timestamp": 1581273888,
"user_id": "2",
"user_profile_id": "4f3d8946-4423-11ea-bbb8-b7af30354b4a",
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjb20uYW1pbm9jb20iLCJhdWQiOiJjb20uYW1pbm9jb20iLCJ0eXBlIjoiYWNjZXNzIiwianRpIjoiNUZsNGVkc3Y3UyIsImlhdCI6MTU4MTI3Mzg4OCwibmJmIjoxNTgxMjczODg4LCJleHAiOjE1ODEyNzc0ODgsImRhdGEiOnsidXNlcklkIjoiMiIsInVzZXJfZW1haWwiOiJzYW0uYm9jaGFyb3ZAMjRpLmNvbSIsInNlc3Npb25faWQiOiI4ZjQ0Y2RmMTdkOGRlY2JiNDU1N2NlIn0sInN1YiI6IjIiLCJwcm9maWxlIjoiNGYzZDg5NDYtNDQyMy0xMWVhLWJiYjgtYjdhZjMwMzU0YjRhIn0.faCZL74jn4aigrwN2pIKl2uusjB8z1d8by3aVmCmi5o",
"expires_at_timestamp": 1581277488,
"refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJjb20uYW1pbm9jb20iLCJhdWQiOiJjb20uYW1pbm9jb20iLCJ0eXBlIjoicmVmcmVzaCIsImp0aSI6IlBkeUJ2THFacU8iLCJpYXQiOjE1ODEyNzM4ODgsIm5iZiI6MTU4MTI3Mzg4OCwiZXhwIjoxNTgzODY1ODg4LCJkYXRhIjp7InVzZXJJZCI6IjIiLCJ1c2VyX2VtYWlsIjoic2FtLmJvY2hhcm92QDI0aS5jb20iLCJzZXNzaW9uX2lkIjoiOGY0NGNkZjE3ZDhkZWNiYjQ1NTdjZSJ9LCJzdWIiOiIyIiwicHJvZmlsZSI6IjRmM2Q4OTQ2LTQ0MjMtMTFlYS1iYmI4LWI3YWYzMDM1NGI0YSJ9.cHfqL0DopjCW6sRePeV-njbOHzfzYhtsr2IIwVnmn-c"
}
}
}
Access Token Usage:
The access token that are obtained from the above endpoints can be used to access all the new APIs and legacy APIs. Clients are expected to provide the token in the "Authorization" header,
for example:
GET /channels/{channel_id}/relationships/streams
HTTP/1.1
Host: customer.domain:443
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJBbWlub1RWIEFQSSIsImlhdCI6MTUzMTgzNDI0MSwiZXhwIjoxNTYzMzcwMjQxLCJhdWQiOiJ3d3cuYW1pbm9jb20uY29tIiwic3ViIjoiYW5keS5iZWFrQGFtaW5vY29tLmNvbSJ9.BL5bRDANTPJqTSiPdUWKN3xSEJTqdVoDuwqrYSaW1xY
cache-control: no-cache
We recommend that the client does not rely on any claims in the token as these may change without notice.
Renewing an access token:
Every endpoint that provides access token will also provide a refresh token, in order to renew the access token.
The token is renewed by calling the createToken endpoint with grant_type=refresh_token User Authentication#/Account%20Authentication/createAccessToken
MUST use the refresh token obtained from the previous authentication.
Refresh token will have an expiration time, if expired repeat steps from How to get Access Token block.
Logging out:
Neither tokens or sessions are stored in the system so there is no need or means to revoke the session or the tokens. The only thing that client needs to perform in order to "log out" the user is to delete the stored tokens.