Managing authorizations (issued tokens) granted for a client by a user

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

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.
Item
Description
subject
Unique user ID  *REQUIRED
start
Start index of search results, inclusive (The default value is 0)
end
End index of search results, exclusive (The default value is 5)
developer
Unique Developer ID (The default value is null)


Response


Successful response


JSON including the following parameters is provided with status code 200.
Item
Description
start
Start index of search results (inclusive)
end
End index of search results (exclusive)
developer
Unique developer ID
totalCount
The total number of clients that meet the conditions
clients
An array of clients. Format of the client information is the same as ones in other responses of some APIs e.g. /client/get
subject
Unique 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.
Item
Description
subject
Unique user ID *REQUIRED
scopes
An 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.
Item
Description
subject
Unique 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 = ...)."
}
How did we do with this article?