> ## Documentation Index
> Fetch the complete documentation index at: https://developers.authlete.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Checking if an access token has particular scopes

> Information on utilizing Authlete's API feature to determine if an access token has specific scopes for validation in a resource server.

## Overview

Authlete's [/auth/introspection](/api-reference/introspection-endpoint/process-introspection-request) API has a feature that checks if an access token for introspection has particular token. You can specify the scopes as values of an array, in a request to the API.

## Checking scopes associated with a token

Here we assume there is an “Order API” in a resource server. It checks an access token attached with a request to the API and processes the request at least when the token has a **payment** scope.

With Authlete's [/auth/introspection](/api-reference/introspection-endpoint/process-introspection-request) API, you have two implementation options:

1. The resource server sends only the access token to [/auth/introspection](/api-reference/introspection-endpoint/process-introspection-request) API, to get “a list of scopes associated with the token” and determine if it has the **payment** scope
2. The resource server sends “scopes that the token must have” along with the access token to [/auth/introspection](/api-reference/introspection-endpoint/process-introspection-request) API, and gets a response that states if the token is valid

The latter option relatively reduces the complexity of resource server implementation as Authlete manages to check the existence of the scopes.\\

<img src="https://mintcdn.com/authlete/EJDZNZMvOu_9CJHJ/configuration-reference/endpoints/checking-scopes-associated-with-token.png?fit=max&auto=format&n=EJDZNZMvOu_9CJHJ&q=85&s=09125b6a951ac4b3bc3afa83f9ce817d" alt="checking-scopes-associated-with-token" width="960" height="463" data-path="configuration-reference/endpoints/checking-scopes-associated-with-token.png" />

## How to use

[/auth/introspection](/api-reference/introspection-endpoint/process-introspection-request) API can accept "scopes" parameter. You can use it to check if an access token that is a value of "token" parameter covers particular scopes that are specified the "scopes" parameter.

The "scopes" parameter is an array. It includes each scope as a value. For example, you can check if an access token covers "account" and "payment" scopes by describing them as follows:

```
"scopes": **["account","payment"]**
```

Note that the following example doesn't work as expected.

```
"scopes": ["account payment"]
```

Authlete would recognize this value as a single scope, "account payment", that doesn't actually exist, and understand no values are specified for the scopes parameter:

```
"scopes": []
```

As a result, Authlete would do nothing in terms of checking scopes.

## Examples

The following request/response examples show how to check if an access token (MhVD...) with three scopes (**openid**, **profile**, and **payment**) has particular scopes. curl command is used for the examples. (folded for readability)

### When it has particular scopes

* Request

The request is made to check if the token has **openid** and **payment**  scopes.

```
curl -s -X POST .../auth/introspection \
     -u $apiKey:$apiSecret \
     -H 'Content-type: application/json' \
     -d '{"token":"MhVD...","scopes": **["openid","payment"]}'
```

* Response

Authlete sends back a successful response as the token is valid.

```
{
   "type": "introspectionResponse",
   "resultCode": "A056001",
   "resultMessage": "[A056001] The access token is valid.",
   "action": "OK",
   "clientId": ...,
   "expiresAt": ...,
   "responseContent": "Bearer error=\"invalid_request\"",
   "scopes": [
     "openid",
     "profile",
     "payment"
   ],
   "subject": "testuser01",
   ...
}
```

### When it doesn't have particular scopes

* Request

The request is made to check if the token has **openid** and **email** scopes.

```
curl -s -X POST .../auth/introspection  -u $apiKey:$apiSecret  \
-H 'Content-type: application/json'  \
-d '{"token":"MhVD...","scopes":**["openid","email"]}'
```

* Response

Authlete sends back an error response as the token that doesn't have the **email** scope is not valid.

```
{
  "type": "introspectionResponse",
  "resultCode": "A064302",
  "resultMessage":
    "[A064302] The access token does not cover the required scope **'email'.",**  "action": "FORBIDDEN",
  "clientId": ...,
  "expiresAt": ...,
  "responseContent":
    "Bearer error=\"insufficient_scope\",
     error_description=\"[A064302] The access token does not cover
       the required scope **'email'.\",**     error_uri=\"https://docs.authlete.com/#A064302\",
     scope=\"openid email\"",
  "scopes": [
    "openid",
    "profile",
    "payment"
  ],
  "subject": "testuser01",
...
}
```