Skip to main content

​
Preface

This article describes some Authlete APIs for retrieving, changing and revoking authorization granted for a client by a user. They would be useful in some use cases, for example:
  • A user logs in to an API provider (authorization server) website and checks what clients he or she has granted access
  • An API provider deletes tokens for a particular client as per request from a user
user-centric-token-management

​
1. Obtaining a list of clients that have tokens granted by a user

/client/authorization/get/list API provides a list of clients which have been authorized a certain user (i.e. which have had tokens granted by the user).

​
Request

A request will be made using either GET or POST. 
GET /api/client/authorization/get/list/<subject>

GET /api/client/authorization/get/list?subject=<subject>

POST /api/client/authorization/get/list
application/x-www-form-urlencoded

POST /api/client/authorization/get/list
application/json
Request parameters are as follows.
ItemDescription
subjectUnique user ID  *REQUIRED
startStart index of search results, inclusive (The default value is 0)
endEnd index of search results, exclusive (The default value is 5)
developerUnique Developer ID (The default value is null)

​
Response

​
Successful response

JSON including the following parameters is provided with status code 200.
ItemDescription
startStart index of search results (inclusive)
endEnd index of search results (exclusive)
developerUnique developer ID
totalCountThe total number of clients that meet the conditions
clientsAn array of clients. Format of the client information is the same as ones in other responses of some APIs e.g. /client/get
subjectUnique user ID

​
Failed response

The following JSON object is provided with status code 400, 403, 500 etc. 
application/json
{
  "resultCode": ...,
  "resultMessage": ...
}

​
Example

  • Request
The following example is a request to retrieve a list of clients granted authorization by user “testuser01”. 
curl -s -X POST $AL_API/client/authorization/get/list \
-u ...:... \
-H 'Content-type: application/json' \
-d **'{"subject":"testuser01"}'**
  • Response
Authlete sends back a response including a list of clients in “clients”. 
{
   "type": "authorizedClientListResponse",
"clients": [
      {
         "clientId": 17566160603766,
         "clientIdAliasEnabled": false,
         "clientName": "FAPI Client",
         "developer": "authlete_14500880170338"
      }
   ],**   "end": 5,
   "start": 0,
   "totalCount": 1,
   "subject": "testuser01"
}

​
2. Updating scopes of authorizations (tokens) for a client by a user

/client/authorization/update API allows an authorization server to update scopes of tokens for a single client, which have been granted by a certain user.

​
Request

A request will be made using POST. Its URL includes clientId. 
POST /api/client/authorization/update/<clientId>
application/x-www-form-urlencoded

POST /api/client/authorization/update/<clientId>
application/json
Request parameters are as follows.
ItemDescription
subjectUnique user ID *REQUIRED
scopesAn array of new scopes
  • If a non-null value is given, the new scopes are set to all existing access tokens
  • If an API call is made using “Content-Type: application/x-www-form-urlencoded”, scope names listed in this request parameter should be delimited by spaces (after form encoding, spaces are converted to ’+’) |

​
Response

JSON including the following parameters is provided with status code 200, 400, 403, 500 etc. 
application/json
{
  "resultCode": ...,
  "resultMessage": ...
}

​
Example

  • Request
The following example is a request to update tokens issued to a client “17566160603766” as per granted by a user “testuser01”. A new value of “scopes” for the tokens will be “payment”. 
curl -s -X POST $AL_API/client/authorization/update/**17566160603766** \
-u ...:... \
-H 'Content-type: application/json' \
-d '{
    "subject":"testuser01", "scopes":"payment"   }'
  • Response
Authlete send back a response stating that the access tokens have been updated. 
{
    "resultCode": "A138001",
    "resultMessage": "[A138001] **Updated 4 access token(s)** issued to the client (ID = 17566160603766) of the service (API Key = ...)."
}

​
Revoking authorization for one of clients which have been authorized by a user

/client/authorization/delete API allows authorization server to revoke tokens by specifying both a client and a user.

​
Request

A request will be made using either DELETE or POST. Its URL includes clientId. 
DELETE /api/client/authorization/delete/<clientId>/<subject>

DELETE /api/client/authorization/delete/<clientId>?subject=<subject>

POST /api/client/authorization/delete/<clientId>
application/x-www-form-urlencoded

POST /api/client/authorization/delete/<clientId>
application/json
Request parameters are as follows.
ItemDescription
subjectUnique user ID *REQUIRED

​
Response

JSON including the following parameters is provided with status code 200, 400, 403, 500 etc. 
application/json
{
  "resultCode": ...,
  "resultMessage": ...
}

​
Example

  • Request
The following example is a request to delete tokens issued to a client “17566160603766” as per granted by a user “testuser01”. 
curl -s -X POST $AL_API/client/authorization/delete/**17566160603766** \
-u ...:... \
-H 'Content-type: application/json' \
-d '{
    "subject":"testuser01"   }'
  • Response
Authlete send back a response stating that the access tokens have been deleted. 
{
   "resultCode": "A137001",
   "resultMessage": "[A137001] **Deleted 4 access token(s)** issued to the client (ID = 17566160603766) of the service (API Key = ...)."
}