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
BPLAT-12506 introduced authentication and receiving of 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 using User Profile ID:
This feature is available only after the User Profiles feature is in place
- Every user has an associated default profile ID, which is available as an identity in the token with the attribute
user_profile_id, - To get a profile based access token use the end point User profiles#/Authentication%20token/getProfileAuthToken
Response from the end point:
{
"data": [
{
"type": "AuthenticationTokens",
"id": "9bc6871e-ce26-4b8a-96f6-e6688599d938",
"attributes": {
"login_timestamp": 1538126476,
"user_id": 1234,
"user_profile_id": "84eb61a9-75d4-42c7-8c15-84c3d7776227",
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJBbWlub01vdmUiLCJpYXQiOjE1Mzc1MjIxNzQsImV4cCI6MTUzODEyNjk3OSwiYXVkIjoid3d3LmJvb3h0di5maSIsInN1YiI6ImV4YW1wbGVfdXNlckBlbWFpbGRvbWFpbi5jb20iLCJwcm9maWxlX2lkIjoiNmM3Zjk0YWYtYjYwMy00ZjM5LTgzODQtZjEyMjI2ZWE5ZDRjNmM3Zjk0YWYtYjYwMy00ZjM5LTgzODQtZjEyMjI2ZWE5ZDRjIiwidHlwZSI6ImFjY2VzcyIsInN0Yl9zZXJpYWxfbm8iOiI2MTU1MDAyNjYxNjIifQ.RW6NdDE_kGgkOVKqodeT1fDdxU7Slaf551rp5ctBcFc",
"expires_at_timestamp": 1538126476,
"refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJBbWlub01vdmUiLCJpYXQiOjE1Mzc1MjIxNzQsImV4cCI6MTU0NTk4OTM3OSwiYXVkIjoid3d3LmJvb3h0di5maSIsInN1YiI6ImV4YW1wbGVfdXNlckBlbWFpbGRvbWFpbi5jb20iLCJ0eXBlIjoicmVmcmVzaCJ9.9Pxzv0oGxjZmAIpZiH-aiue7LwAMcddPPHnaiOkpb-A"
}
}
]
}
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.