Skip to main content
Generic tokens store arbitrary payloads (for example SEPA credentials, API keys, or other sensitive data) with optional schemas for validation and filtering.

Overview

Generic tokens provide a flexible way to store non-card data securely. Payloads are JSON-serializable and can be shaped and validated using Types. Types defined in Types can be used as schemas for generic token payloads and enable filters and validations.

When to use generic tokens

  • SEPA bank account credentials
  • API keys and secrets
  • Custom authentication tokens
  • Any other structured sensitive data that benefits from secure storage and schema validation

Payload schema

When you create a token, the payload can follow a schema in one of two ways:
  • type_id: the ID of a registered type.
  • schema: an inline JSON Schema, for a token whose structure you don’t want to register as a type.
An inline schema is checked like a type’s schema, with the same dialects and data classification rules and refusals. Guardian then validates the payload against it and keeps the schema on the token unchanged for its whole life. An inline schema isn’t a registered type: it doesn’t appear in the list of types and can’t be reused for another token. Unlike a type’s schema, an inline schema is bounded. It is refused with a 422 on schema when:
  • its compact JSON encoding is larger than 32768 bytes: must be at most 32768 bytes as JSON;
  • it nests objects and arrays deeper than 32 levels, counting the root object as level 1: must not nest deeper than 32 levels.
Give at most one of type_id and schema. A request with both returns a 422 with the message provide either type_id or schema, not both on schema. A null value counts as not sent. A token created with neither has no schema, and every leaf of its payload is any.

Reading a token

Get token details and Get tokens return both type_id and schema. The one the token wasn’t created with is null, and both are null for a token created with neither. The payload itself is only returned by Get token payload.