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
Event History: Obtain the event history for this MT
Subtokens: Get the subtoken tree for this MT
List: Lists all Mytokens for this user
Notifications: Get notifications and calendars associated with this MT

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
`token_update`	OPTIONAL	A nested `MytokenResponse` object. This is included if the provided mytoken was rotated during the request.

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

Event History¶

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

Event History Request¶

To query the event history for a mytoken the client makes an event 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 `event_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": "event_history",
    "mytoken": "eyJhbGcio..."
}

Event 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
`token_update`	OPTIONAL	A nested `MytokenResponse` object. This is included if the provided mytoken was rotated during the request.

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
`token_update`	OPTIONAL	A nested `MytokenResponse` object. This is included if the provided mytoken was rotated during the request.

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
`tags`	OPTIONAL	A JSON Array of MTTagInfo objects representing the tags assigned to this mytoken

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,
            "tags": [
                {
                    "tag": "production",
                    "color": "#ff5733",
                    "include_children": true
                }
            ]
        },
        "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
`token_update`	OPTIONAL	A nested `MytokenResponse` object. This is included if the provided mytoken was rotated during the request.

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
                    }
                }
            ]
        }
    ]
}

Notifications¶

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

Notifications Request¶

To query the notifications and calendars for a mytoken the client makes a notifications 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 `notifications`
`mytoken`	REQUIRED	The mytoken
`mom_ids`	OPTIONAL	If given, the notifications and calendars 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 notifications and calendars for the mytoken in the mytoken parameter. This is usually not needed, but it can be useful if additionally, notifications and calendars for other mytokens are requested.

Attention

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

Example

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

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

Notifications Response¶

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

Parameter	Necessity	Description
`notifications`	OPTIONAL	A JSON Array of notification entries
`calendars`	OPTIONAL	A JSON Array of calendar entries
`mom_id_mapping`	OPTIONAL (if multiple `mom_ids` were requested)	A map of mom_id to notifications and calendars
`token_update`	OPTIONAL	A nested `MytokenResponse` object. This is included if the provided mytoken was rotated during the request.

Each notification entry has the following parameters:

Parameter	Necessity	Description
`notification_id`	REQUIRED	The unique identifier for the notification
`notification_type`	REQUIRED	The type of the notification
`management_code`	REQUIRED	The management code for the notification
`notification_classes`	REQUIRED	A JSON Array of notification class objects subscribed to this notification
`subscribed_tokens`	OPTIONAL	A list of the mom ids of the tokens that are subscribed to this notification
`tags`	OPTIONAL	A JSON Array of tag objects associated with the notification
`ws`	OPTIONAL	A URI where the websocket for this notification can be connected
`user_wide`	REQUIRED	Whether the notification is user-wide

Each calendar entry has the following parameters:

Parameter	Necessity	Description
`id`	REQUIRED	The unique identifier for the calendar
`ics_path`	REQUIRED	A URI where the calendar's ICS can be downloaded
`description`	OPTIONAL	A description of the calendar
`tags`	OPTIONAL	A JSON Array of tag objects associated with the calendar
`subscribed_tokens`	REQUIRED	A list of the mom ids of the tokens that are included in this calendar

Example

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

{
    "notifications": [
        {
            "id": "59ckwFkBdQoqo6t5jAkdnek24kd9HvUB",
            "type": "expiring_soon",
            "description": "Token expires in 24 hours"
        }
    ],
    "calendars": [
        {
            "id": "59ckwFkBdQoqo6t5jAkdnek24kd9HvUB",
            "ics_path": "https://mytoken.example.com/calendars/59ckwFkBdQoqo6t5jAkdnek24kd9HvUB",
            "description": "CI/CD pipeline tokens",
            "tags": [
                {
                    "tag": "CI",
                    "color": "#3357ff"
                }
            ],
            "subscribed_tokens": [
                "rB8g1NhHqRNQL8S38DkzQgMJ9Df7wVmnuX1dkSk3kAlsUQM6igudDWL3ZMYf4xm1AL8/pQdGAetBa/y5ktydrg==",
                "Kqi9Jvwz5v4QCpNGrx8oon5ZJmtQEZ+zK/s52ynWpUMkl4kjEMskeLL3RqTkhvC6FOk7mTs1tJPdLXPx8OZ+uQ=="
            ]
        }
    ]
}

Last update: April 14, 2026 07:17:04