Introspect endpoint

This endpoint is used to check whether a token is valid, and whether the token was actually issued by your Authentication Cloud instance. You can use the endpoint to verify the authenticity of transaction tokens after successful authentications, such as after in-band operations.

note

This endpoint is modeled after OAuth 2 Token Introspection (RFC7662), thus the expected request payload is not JSON, but application/x-www-form-urlencoded.

HTTP request

POST https://{instance}.mauth.nevis.cloud/api/v1/introspect

Request body parameters

Parameter	Type	Required/Optional	Description
token	string	required	The token to be verified, issued or provided by the Authentication Cloud. See the list of supported token below.

Supported tokens

The following tokens are supported by the introspect endpoint:

• Access key: Used for authenticating API requests from server side. See the Authentication for details.
• Transaction token: Returned by the Status endpoint. Use this token to verify whether the operation was really executed by your Authentication Cloud instance.
• Status token: Returned by starting a registration or approval operation. Use this token to get the status of the registration or approval operation with the status endpoint.
• Intent token: Short-living one-time token which is restricted to specific user and specific intent. See the Intent endpoint for details.

Example HTTP request

cURL

Code sample for checking the validity and authenticity of a token

# Set $token
curl "https://$instance.mauth.nevis.cloud/api/v1/introspect" \
  -XPOST \
  -H "Authorization: Bearer $access_key" \
  --data-urlencode "token=$token"

Python 3

Code sample for checking the validity and authenticity of a token

data = {'token': 'eyJhb...lc3g'}
resp = requests.post(f'https://{instance}.mauth.nevis.cloud/api/v1/introspect',
                     headers = {'authorization': f'Bearer {access_key}'},
                     data = data)
print(resp.json())

HTTP response

Field	Type	Description
active	boolean	Indicator of whether the presented token is currently active and is issued by this instance. If false is returned, then the token is never OK and not to be trusted.
iat	timestamp	Expiration time, measured in the number of seconds since January 1 1970 UTC and indicating when this token expires, as defined in JSON Web Token (JWT) specification.
nbf	timestamp	Identifies the time before which the token must not be accepted for processing. It is measured in the number of seconds since January 1 1970 UTC, indicating when this token becomes valid, as defined in JSON Web Token (JWT) specification.
sub	string	The subject of the token, in case of transaction tokens, the userId of the user in the operation.
aud	enum	Audience. Service-specific string identifier or list of string identifiers representing the intended audience for this token, as defined in JSON Web Token (JWT) specification.
iss	URI	The issuer of this token, as defined in the JSON Web Token (JWT) specification. The issuer is your Authentication Cloud instance, and it is presented in the following format: https://{instance}.mauth.nevis.cloud/.
jti	string	Unique token identifier, as defined in the JSON Web Token (JWT) specification. In case of status tokens, this is the transaction identifier.
scope	string	Only present when an intent token is used. Contains the specific operation and channel to which the intent token is restricted to. For example enroll:sms,app. See the Intent endpoint for details.

Example HTTP response

Active and valid access key

200 OK: Active and valid access key

{
  "active": true,
  "iat": 1642436165000,
  "sub": "c8edb1d1-6dac-470f-b2fb-c25277a5c5b6",
  "aud": "api",
  "iss": "https://{instance}.mauth.nevis.cloud/"
}

Valid transaction token

200 OK: Valid transaction token

{
  "active": true,
  "iat": 1654759374000,
  "sub": "fc6bf4bb-9f46-48a9-95d6-91051a3d6468",
  "aud": "transaction",
  "iss": "https://{instance}.mauth.nevis.cloud/"
}

Valid status token

200 OK: Valid status token

{
  "active": true,
  "iat": 1662625372000,
  "sub": "29886449-532e-4de7-923d-845e94b81762",
  "aud": "status",
  "iss": "https://{instance}.mauth.nevis.cloud/",
  "jti": "fdc3e23e-9ec8-4375-9b13-9a586270a9cd"
}

Valid intent token

200 OK: Valid intent token

{
  "iat": 1662626062,
  "exp": 1662626662,
  "aud": "intent",
  "iss": "https://{instance}.mauth.nevis.cloud/",
  "sub": "0afb658e-9536-430f-a69b-d53a7a603be1",
  "scope": "enroll:sms,app"
}

Invalid token

200 OK: Invalid token

{
  "active": false
}