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
mom_id RECOMMENDED The mom id of the token

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:subtokens"
    ]
  }
}

History

This operation requires the tokeninfo:history capability or the manage_mytokens:history capability when using a mom id.

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
mom_ids OPTIONAL If given, the event history for the mytokens associated with these mom ids is returned, not for the token in the mytoken parameter, the mytoken parameter is still required and used as authorization.

Important

In mom_ids the special id this can be used to request the event history for the mytoken in the mytoken parameter. This is usually not needed, but it can be useful if additionally, event histories for other mytokens are requested.

The special value children can be used to request the event history for all the children (recursively) of the mytoken in the mytoken parameter. It will not include the event history for the subject token itself.

The special value children@<mom_id> can be used to request the event history for all the children (recursibely) of the mytoken with the <mom_id>.

Attention

Requesting event history for any mytoken other than itself, requires the authorization mytoken to either be a parent or having the manage_mytokens:history capability.

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
mom_id REQUIRED The mom id of the mytoken that is linked to this 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,
            "mom_id": "ihmvVP/DGX7xyqKPr9wXRP582wyaqgQG8o7adFNQlqk59s6TGmhl/M9v2KY3OrzpuWA/z+LS5gS08gWHres09w=="
        },
        {
            "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,
            "mom_id": "ihmvVP/DGX7xyqKPr9wXRP582wyaqgQG8o7adFNQlqk59s6TGmhl/M9v2KY3OrzpuWA/z+LS5gS08gWHres09w=="
        },
        {
            "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,
            "mom_id": "ihmvVP/DGX7xyqKPr9wXRP582wyaqgQG8o7adFNQlqk59s6TGmhl/M9v2KY3OrzpuWA/z+LS5gS08gWHres09w=="
        },
        {
            "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,
            "mom_id": "ihmvVP/DGX7xyqKPr9wXRP582wyaqgQG8o7adFNQlqk59s6TGmhl/M9v2KY3OrzpuWA/z+LS5gS08gWHres09w=="
        }
    ]
}

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
mom_id REQUIRED A mom id (manage-other-mytokens ID) for this mytoken that can be used to manage it (revocation, event history);
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
expires_at REQUIRED if token expires A numeric time value (UNIX timestamp) indicating when this mytoken expires

Example

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

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

List Mytokens

This action requires the manage_mytokens:list 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",
                "mom_id": "fedcba",
                "created": 1634311516,
                "expires": 1634311517
            }
        },
        {
            "token": {
                "ip": "127.0.0.1",
                "name": "mytoken-web",
                "mom_id": "abcdef",
                "created": 1636373529,
                "expires_at": 1636473529
            },
            "children": [
                {
                    "token": {
                        "ip": "127.0.0.1",
                        "name": "mytoken-web MT for list_mytokens",
                        "mom_id": "aabbcc",
                        "created": 1636384021,
                        "expires_at": 1636473529
                    }
                },
                {
                    "token": {
                        "ip": "127.0.0.1",
                        "name": "mytoken-web MT for AT",
                        "mom_id": "ddeeff",
                        "created": 1636384026,
                        "expires_at": 1636393529
                    }
                }
            ]
        }
    ]
}

Last update: August 10, 2023 08:35:46
Back to top