ErtisAuth keeps track of every token pair it issues. You can list the active tokens of a membership to show users where they are signed in, and list the revoked tokens for auditing.

Active tokens#

An active token is a token pair that is neither expired nor revoked.

json

{
	"_id": "66f1c0d2a4b5c6d7e8f901c0",
	"access_token": "eyJhbGciOiJIUzI1NiIs…",
	"refresh_token": "eyJhbGciOiJIUzI1NiIs…",
	"token_type": "Bearer",
	"expires_in": 3600,
	"refresh_token_expires_in": 86400,
	"created_at": "2026-01-01T12:00:00Z",
	"expire_time": "2026-01-01T13:00:00Z",
	"retain_until": "2026-01-02T12:00:00Z",
	"user_id": "66f1c0d2a4b5c6d7e8f90127",
	"username": "ada",
	"email_address": "ada@example.com",
	"first_name": "Ada",
	"last_name": "Lovelace",
	"client_info": {
		"ip_address": "203.0.113.42",
		"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_0) …"
	},
	"membership_id": "66f1c0d2a4b5c6d7e8f90123"
}

Field	Description
`expire_time`	When the access token expires
`retain_until`	The later of the access and refresh token expiry. MongoDB removes the record a few minutes after this time.
`client_info`	The IP address and user agent of the sign-in, from the request or from the `X-IpAddress` and `X-UserAgent` headers

Warning: active token records contain the tokens themselves. Anyone who can read them can act as those users. Grant tokens.read only to trusted operators, and use select to leave the tokens out when you show sessions in a user interface.

Endpoints#

All routes are under /memberships/{membershipId}.

Method	Route	Description	Permission
`GET`	`/active-tokens/{id}`	Get an active token	`tokens.read.{id}`
`GET`	`/active-tokens`	List active tokens	`tokens.read`
`POST`	`/active-tokens/_query`	Query active tokens	`tokens.read`
`POST`	`/active-tokens/_aggregate`	Run an aggregation pipeline	`tokens.read`

Examples#

The sessions of a user, without the token values:

shell

curl -X POST 'https://auth.example.com/memberships/<membership_id>/active-tokens/_query?sort=created_at%20desc' \
	-H 'Authorization: Bearer <access_token>' \
	-H 'Content-Type: application/json' \
	-d '{
		"where": { "user_id": "66f1c0d2a4b5c6d7e8f90127" },
		"select": { "access_token": 0, "refresh_token": 0 }
	}'

The number of signed-in users per day:

json

[
	{ "$group": { "_id": { "$dateToString": { "format": "%Y-%m-%d", "date": "$created_at" } }, "users": { "$addToSet": "$user_id" } } },
	{ "$project": { "day": "$_id", "count": { "$size": "$users" } } },
	{ "$sort": { "day": -1 } }
]

To end a session, revoke its token. To sign a user out everywhere, revoke with logout-all=true, change their password or freeze them.

Revoked tokens#

Revoked tokens are kept until they would have expired anyway, so that they are rejected until then.

json

{
	"_id": "66f1c0d2a4b5c6d7e8f901d0",
	"token": "eyJhbGciOiJIUzI1NiIs…",
	"token_type": "Bearer",
	"revoked_at": "2026-01-01T12:30:00Z",
	"retain_until": "2026-01-02T12:00:00Z",
	"user_id": "66f1c0d2a4b5c6d7e8f90127",
	"username": "ada",
	"email_address": "ada@example.com",
	"first_name": "Ada",
	"last_name": "Lovelace",
	"membership_id": "66f1c0d2a4b5c6d7e8f90123"
}

Endpoints#

Method	Route	Description	Permission
`GET`	`/memberships/{membershipId}/revoked-tokens`	List revoked tokens	`tokens.read`
`POST`	`/memberships/{membershipId}/revoked-tokens/_query`	Query revoked tokens	`tokens.read`