Manage Tokens

The IAM service provide a full life cycle to manage api keys, getting metadata or setting new privileges to a token.

The actions that are available are:

• Revocation - Revoking a token
• Rotation - Revoking the provided token and generating a new one
• Update IP - Updating the ip restriction list to remove and address or add new one for the verification process
• Privilege - Updating the privilege for a given token.
• Metadata - Fetches extensive audit logs.
• List - Getting a list of tokens metadata and counts for a given user

For the service users, the actions is behind a full authentication flow, each needs to succeeded before an action can be performed:

• requireAccessToken Requires the access token header to be present
• requireRefreshToken Requires the refresh token to be present
• getFingerPrint Gets the finger prints for MFA
• checkForActiveMfa MFA cache
• protectRoute Enforces authentication, and perform the 9 mfa checks,
• contentType('application/json') Enforces application/json,
• express.json To limit the body size to 1kb
• apiTokensController The actions happens here

If the client is not authenticate, cannot be found, have an active MFA, the actions will fail, with the appropriate response.

For the library users you call the privateActionManager for all actions except from the List actions, to enforce the same security as the routes. You can also however call it's underlying methods directly for custom use cases.

Library

The privateActionManager

The privateActionManager acts as the high-level coordinator for all dashboard driven token operations. It serves as a security layer between the user’s intent and the cryptographic operations required to modify or rotate API keys.

Instead of the client interacting with raw, hashed tokens directly, the manager uses a Public Identifier, a non sensitive key, to locate the correct record and ensure the authenticated user actually owns the resource they are trying to modify.

Signature

async function privateActionManager(
    userId: number,
    tokenId: number,
    publicIdentifier: string,
    name: string,
    options: ActionArgs,
): Promise<ActionManagerResult>

Parameters

Behavior

The manager performs a three-step process before executing any action to prevent unauthorized access:

• Checksum Validation: It first validates the publicIdentifier format and checksum. If the identifier is malformed, the request is dropped before querying the database.
• It executes a query that requires five points of data to match: id, user_id, name, public_identifier, and a valid = 1 status.

Once identity is confirmed, it extracts the api_token hash from the database and dispatches it to the specific utility (revoke, rotate, etcetera).

Supported Actions

The manager handles five distinct lifecycle actions through the options argument:

• revoke: Marks the token as invalid. No further requests using this key will be accepted by the verification process.
• rotate: An atomic replace operation. It generates a new raw key while inheriting the attributes of the old one. Same prefix, remaining expiry, and existing IP restrictions.
• metadata: Returns extensive audit data, including when the token was last used and total usage counts.
• ip-restriction-update: Updates the whitelist of IP addresses allowed to use the token.
• privilege-update: Modifies the privileges of the token.

Return type

privateActionManager returns the response of the underlying functions, even it these actions fails. Explore the docs to learn more.

When privateActionManager its self fails, it returns the following:

Checksum validations failure:

{
  ok: false,
  date: new Date().toISOString(),
  reason: 'Invalid identity'
}

When the query resulted in 0 rows, or when the provided action is not found:

{
 ok: false,
 date: new Date().toISOString(),
 reason: 'Bad Request'
}

Database failure:

{
  ok: false,
  date: new Date().toISOString(),
  reason: 'Server Error'
}

Service

As mentioned above, to perform any action, your client needs to be fully authenticated, with a valid refresh token a valid access token and a canary_id cookie. The session also should not have any active MFA or anomaly associated with it.

Each actions enforces the full authentication life-cycle before it perform any actions.

How ever every endpoint haves a different path, rate limiters, methods and a different body shape for POST requests.

Explore the logs below to learn how to perform an action.

Some of the failure response are identical for all actions, which are the following:

If the body is not valid or missing required values 400 will be returned:

HTTP/1.1 400 Bad request
Content-Type: application/json; charset=utf-8

{
  "ok": false,
  "date": "current date",
  "reason": "Bad Request"
}

If the body contains HTML:

HTTP/1.1 403 Bad request
Content-Type: application/json; charset=utf-8

{
 "banned": true
}

Rate Limits:

HTTP/1.1 429
Content-Type: application/json; charset=utf-8
Retry-After: number
{
  "error": "Too many requests",
  "retry": "number",
}

Documentation