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 = ...)."
}