Skip to content

Token Info Endpoint

The tokeninfo endpoint is an endpoint to obtain various information about a specific Mytoken or all Mytokens.

The endpoint supports the following operations:

  • Introspect: Obtain information about this MT: validity, content, usages
  • History: Obtain the event history for this MT
  • Subtokens: Get the subtoken tree for this MT
  • List: Lists all Mytokens for this user.

All of these actions require the appropriate capability and can be enabled/disabled by the server administrator for a mytoken deployment.

Introspect

This operation requires the tokeninfo:introspect capability. It is especially useful for checking if a token is valid and to "decode" a short mytoken.

Introspection Request

To introspect a mytoken the client makes an introspection request to the tokeninfo endpoint by adding the following parameters using the application/json or application/x-www-form-urlencoded format in the HTTP request entity-body:

Parameter Necessity Description
action REQUIRED MUST be introspect
mytoken REQUIRED The mytoken to introspect

Example

POST /api/v0/token/introspect HTTP/1.1
Host: mytoken.example.com
Content-Type: application/json

{
    "action": "introspect",
    "mytoken": "eyJhbGcio..."
}

Introspection Response

A successful response returns the following parameters using the application/json media type:

Parameter Necessity Description
valid REQUIRED MUST be true iff the token is valid
token_type REQUIRED The type of the mytoken (token or short_token)
token REQUIRED The decoded token payload

Info

If the token has restrictions that restrict the number of usages and the token was already used, the response MUST contain how often the token was already used. In this case the restrictions object in the decoded payload will be extended by fields indicating how often the token was already used. These fields are named: usages_AT_done and usages_other_done.

Example

HTTP/1.1 200 OK
Content-Type: application/json

{
  "valid": true,
  "token_type": "short_token",
  "token": {
    "iss": "https://mytoken.example.com",
    "sub": "...",
    "nbf": 1612367394,
    "iat": 1612367394,
    "jti": "d2a4...",
    "aud": "https://mytoken.example.com",
    "oidc_sub": "...",
    "oidc_iss": "https://op.example.org",
    "restrictions": [
      {
        "scope": "openid profile storage.write",
        "usages_AT": 10,
        "usages_AT_done": 2
      },
      {
        "scope": "openid profile storage.read",
        "usages_AT": 10,
        "usages_AT_done": 4
      }
    ],
    "capabilities": [
      "AT",
      "create_mytoken",
      "tokeninfo_introspect",
      "tokeninfo_history",
      "tokeninfo_tree"
    ]
  }
}

History

This operation requires the tokeninfo:history capability.

History Request

To query the history for a mytoken the client makes a history request to the tokeninfo endpoint by adding the following parameters using the application/json or application/x-www-form-urlencoded format in the HTTP request entity-body:

Parameter Necessity Description
action REQUIRED MUST be history
mytoken REQUIRED The mytoken

Example

POST /api/v0/token/introspect HTTP/1.1
Host: mytoken.example.com
Content-Type: application/json

{
    "action": "history",
    "mytoken": "eyJhbGcio..."
}

History Response

A successful response returns the following parameters using the application/json media type:

Parameter Necessity Description
events REQUIRED A JSON Array of event entries, ordered ascending by time

Each event entry can have the following parameters:

Parameter Necessity Description
event REQUIRED A string indicating the event type
time REQUIRED A numerical time value (UNIX timestamp) indicating the time when this event occurred
comment OPTIONAL A comment string that gives additional information
ip OPTIONAL The IP that was used to trigger the event
user_agent OPTIONAL The user agent that was used to trigger the event

Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "events": [
        {
            "event": "created",
            "comment": "Used grant_type oidc_flow authorization_code",
            "ip": "142.42.42.42",
            "user_agent": "Mozilla/5.0(X11;Linuxx86_64;rv:78.0)Gecko/20100101Firefox/78.0",
            "time": 1636373529
        },
        {
            "event": "tokeninfo_introspect",
            "ip": "142.42.42.42",
            "user_agent": "Mozilla/5.0(X11;Linuxx86_64;rv:78.0)Gecko/20100101Firefox/78.0",
            "time": 1636373530
        },
        {
            "event": "token_rotated",
            "ip": "142.42.42.42",
            "user_agent": "Mozilla/5.0(X11;Linuxx86_64;rv:78.0)Gecko/20100101Firefox/78.0",
            "time": 1636382799
        },
        {
            "event": "tokeninfo_history",
            "ip": "142.42.42.42",
            "user_agent": "Mozilla/5.0(X11;Linuxx86_64;rv:78.0)Gecko/20100101Firefox/78.0",
            "time": 1636382799
        }
    ]
}

Subtokens

This operation requires the tokeninfo:subtokens capability.

Subtokens Request

To query information about a mytoken's subtokens the client makes a subtokens request to the tokeninfo endpoint by adding the following parameters using the application/json or application/x-www-form-urlencoded format in the HTTP request entity-body:

Parameter Necessity Description
action REQUIRED MUST be subtokens
mytoken REQUIRED The mytoken

Example

POST /api/v0/token/introspect HTTP/1.1
Host: mytoken.example.com
Content-Type: application/json

{
    "action": "subtokens",
    "mytoken": "eyJhbGcio..."
}

Subtokens Response

A successful response returns the following parameters using the application/json media type:

Parameter Necessity Description
mytokens REQUIRED A token object holding information about the mytoken and its children

The token object has the following attributes:

Parameter Necessity Description
token REQUIRED A token-data object holding information about the mytoken
children OPTIONAL A JSON Array of token objects - one for each subtoken

The token-data object has the following attributes:

Parameter Necessity Description
name OPTIONAL The name of this mytoken
revocation_id REQUIRED An id for this mytoken that can be used to revoke it; this id is not the same as the JWT's jti and is not intended to be shown to the user.
ip REQUIRED The IP that was used to create the mytoken
created REQUIRED A numeric time value (UNIX timestamp) indicating when this mytoken was created

Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "mytokens": {
        "token": {
            "ip": "127.0.0.1",
            "name": "mytoken-web",
            "revocation_id": "abcdef",
            "created": 1636373529
        },
        "children": [
            {
                "token": {
                    "ip": "127.0.0.1",
                    "name": "mytoken-web MT for list_mytokens",
                    "revocation_id": "aabbcc",
                    "created": 1636384021
                }
            },
            {
                "token": {
                    "ip": "127.0.0.1",
                    "name": "mytoken-web MT for AT",
                    "revocation_id": "ddeeff",
                    "created": 1636384026
                }
            }
        ]
    }
}

List Mytokens

This action requires the list_mytokens capability.

List Mytokens Request

To list information about all mytokens of the user the client makes a list mytokens request to the tokeninfo endpoint by adding the following parameters using the application/json or application/x-www-form-urlencoded format in the HTTP request entity-body:

Parameter Necessity Description
action REQUIRED MUST be list_mytokens
mytoken REQUIRED A mytoken as authorization

Example

POST /api/v0/token/introspect HTTP/1.1
Host: mytoken.example.com
Content-Type: application/json

{
    "action": "list_mytokens",
    "mytoken": "eyJhbGcio..."
}

List Mytokens Response

A successful response is very similar to a successful Subtokens Response and returns the following parameters using the application/json media type:

Parameter Necessity Description
mytokens REQUIRED A JSON Array of token objects holding information about each of user's mytoken and its children

The token object are described under Subtokens Response

Example

HTTP/1.1 200 OK
Content-Type: application/json

{
    "mytokens": [
        {
            "token": {
                "ip": "127.0.0.1",
                "name": "mytoken-web",
                "revocation_id": "fedcba",
                "created": 1634311516
            }
        },
        {
            "token": {
                "ip": "127.0.0.1",
                "name": "mytoken-web",
                "revocation_id": "abcdef",
                "created": 1636373529
            },
            "children": [
                {
                    "token": {
                        "ip": "127.0.0.1",
                        "name": "mytoken-web MT for list_mytokens",
                        "revocation_id": "aabbcc",
                        "created": 1636384021
                    }
                },
                {
                    "token": {
                        "ip": "127.0.0.1",
                        "name": "mytoken-web MT for AT",
                        "revocation_id": "ddeeff",
                        "created": 1636384026
                    }
                }
            ]
        }
    ]
}

Last update: October 20, 2022 08:46:51
Back to top