Authorization Tokens
Authorization Tokens are generated by a user who is given the capability to access the API from a 3rd party service. The token is a proxy of the user, so each action performed with the token is as if it was done by the user who created the token.
Basic Operations
Basic operations of Create, List, and Update are available for tokens. Note: A token may not be destroyed, as the token string itself is valid for it’s validity period. We instead support blocklisting.
List all Tokens
Call to /authorization/token to get all authorization tokens.
Request Object
+ URL
/api/v2/authorization/token
+ Method
GET
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{}
Response Object
Sending this should get you back a valid response, an array with each authorization token in the system.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
[
{
"id": 1,
"hostid": "09e3b2bd",
"username": "open",
"token_name": "od-token-Sat_Sep_12_2020",
"enabled": true,
"systemAuth": false,
"token": "token.redacted.indocumentaion",
"createdAt": "2020-09-12T21:07:50.141Z",
"updatedAt": "2020-09-12T21:07:50.141Z",
"expiresAt": "1600549670138"
},
{
"id": 2,
"hostid": "09e3b2bd",
"username": "open",
"token_name": "od-token-Mon_Sep_21_2020",
"enabled": true,
"systemAuth": false,
"token": "token.redacted.indocumentaion",
"createdAt": "2020-09-21T18:40:35.117Z",
"updatedAt": "2020-09-21T18:40:35.117Z",
"expiresAt": "1601318435112"
}
]
Get token by User
You can also request all tokens generated by a specific user
Request Object
+ URL
/api/v2/authorization/token/$USERNAME/details
+ Method
GET
+ Parameters
user name (string, required, URL param) - the username of the user who generated the token
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
[
{
"id": 1,
"hostid": "09e3b2bd",
"username": "open",
"token_name": "od-token-Sat_Sep_12_2020",
"enabled": true,
"systemAuth": false,
"token": "docoumentation.tokensarentactuallyreal.tokensbutfillertext",
"createdAt": "2020-09-12T21:07:50.141Z",
"updatedAt": "2020-09-12T21:07:50.141Z",
"expiresAt": "1600549670138"
},
{
"id": 2,
"hostid": "09e3b2bd",
"username": "open",
"token_name": "od-token-Mon_Sep_21_2020",
"enabled": true,
"systemAuth": false,
"token": "docoumentation.tokensarentactuallyreal.tokensbutfillertext",
"createdAt": "2020-09-21T18:40:35.117Z",
"updatedAt": "2020-09-21T18:40:35.117Z",
"expiresAt": "1601318435112"
},
{
"id": 3,
"hostid": "09e3b2bd",
"username": "bob_bobson",
"token_name": "bob_bobsons_new_token",
"enabled": true,
"systemAuth": false,
"token": "docoumentation.tokensarentactuallyreal.tokensbutfillertext",
"createdAt": "2020-09-28T17:22:21.334Z",
"updatedAt": "2020-09-28T17:22:21.334Z",
"expiresAt": "1601317341332"
}
]
Response Object
Sending this should get you back a valid response, an array with each token belonging to that user in the system.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
[
{
"id": 1,
"hostid": "09e3b2bd",
"username": "open",
"token_name": "od-token-Sat_Sep_12_2020",
"enabled": true,
"systemAuth": false,
"token": "token.redacted.indocumentaion",
"createdAt": "2020-09-12T21:07:50.141Z",
"updatedAt": "2020-09-12T21:07:50.141Z",
"expiresAt": "1600549670138"
},
{
"id": 2,
"hostid": "09e3b2bd",
"username": "open",
"token_name": "od-token-Mon_Sep_21_2020",
"enabled": true,
"systemAuth": false,
"token": "token.redacted.indocumentaion",
"createdAt": "2020-09-21T18:40:35.117Z",
"updatedAt": "2020-09-21T18:40:35.117Z",
"expiresAt": "1601318435112"
}
]
Create an Authorization Token
You may create an authorization token for yourself, or if you have elevated privileges, for any valid user.
Request Object
+ URL
/api/v2/authorization/token/create
+ Method
POST
+ Parameters
username (string, required, Body) - the username of the user you wish to give a token, yourself if you do not have privledge 'token:manage'
tokenName (string, required, Body) - a unique name to give the token
expiresIn (string, optional, Body) - a JWT time string such as '1y' '10m' etc.
enabled (boolean, optional, Body) - disabled tokens will be rejected when making calls
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{
"username": "bob_bobson",
"tokenName": "test12345"
}
Response Object
Sending this should get you back a valid response, an array containing the newly created token.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
[
{
"id": 6,
"hostid": "09e3b2bd",
"username": "bob_bobson",
"token_name": "test12345",
"enabled": false,
"systemAuth": false,
"token": "wowwhatacool.newtokenforbobbobson.only",
"createdAt": "2020-09-28T18:17:44.502Z",
"updatedAt": "2020-09-28T18:17:44.502Z",
"expiresAt": "1632874664500"
}
]
Update an Authorization Token
You can only update the token name and enabled field after creating a token
Request Object
+ URL
/api/v2/authorization/token/update/$AUTH_ID
+ Method
POST
+ Parameters
auth id (number, required, URL param) - the identifier for the authorization token
tokenName (string, required, Body) - a unique name to give the token
enabled (boolean, optional, Body) - disabled tokens will be rejected when making calls
+ Headers
Content-Type: application/json
token: ThisIsNotARealTokenGenerateYourOwnToken
+ Body
{
"tokenName": "test6789",
"enabled": false
}
Response Object
Sending this should get you back a valid response, an array containing the newly updated token.
+ Headers
X-Powered-By: OpenDrives
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
+ Body
[
{
"id": 6,
"hostid": "09e3b2bd",
"username": "bob_bobson",
"token_name": "test6789",
"enabled": false,
"systemAuth": false,
"token": "wowwhatacool.newtokenforbobbobson.only",
"createdAt": "2020-09-28T18:17:44.502Z",
"updatedAt": "2020-09-28T18:17:44.502Z",
"expiresAt": "1632874664500"
}
]
Destroy an Authorization Token
You cannot destroy an authorization token. Why? Because once a token is created, the text of the token leaves the control of the Atlas system, and the token text is like a key to a lock. The only way to prevent a key from opening a lock, once you loose control of who has they key, is to change your locks.
Luckily, we allow you to set any generated authorization token to 'disabled', which will block list that particular key from your system. To do this, we cannot allow you to delete keys from your system once generated. Please use Authorization Tokens with care!