Docs

API reference

Folders & templates

Organize keys into folders, and control what generated keys look like with key templates.

On this page

Folders group keys inside a service — by store, reseller or campaign. Pass folder_id when you create keys or filter List keys by it. Folder endpoints need folders:read / folders:write.

Key templates set the format of generated keys: prefix, number and length of segments, separator and character set. They need key-templates:read / key-templates:write.

Folders

Create a folder

POST/api/keys/foldersfolders:write

Creates an empty folder in a service.

Bodyapplication/json

  • service_idintegerrequired> 0

    Service the resource belongs to

  • namestringrequired1–32 chars

    Folder name for organizing keys

Response fieldsinside data
  • idinteger

    Folder unique identifier

  • serviceIdinteger> 0

    Service the folder belongs to

  • namestring

    Folder name for organizing keys

  • createdAtstring

    Creation timestamp (ISO 8601)

curl -X POST "https://api.santiauth.com/api/keys/folders" \
  -H "x-api-key: $SANTIAUTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "service_id": 1,
  "name": "Production Keys"
}'
201 Created
{
  "success": true,
  "data": {
    "id": 123,
    "name": "Production Keys",
    "createdAt": "2026-04-30T15:37:35.645Z"
  }
}

List folders

GET/api/keys/foldersfolders:read

Folders of a service, paginated with limit and offset.

Query parameters

  • service_idintegerrequired> 0

    Service the resource belongs to

  • limitnumber1–100

    Maximum number of folders to return (1-100)

    Default 20
  • offsetnumber | null≥ 0

    Number of folders to skip for pagination

    Default 0
Response fieldsinside data
  • idinteger

    Folder unique identifier

  • serviceIdinteger> 0

    Service the folder belongs to

  • namestring

    Folder name for organizing keys

  • createdAtstring

    Creation timestamp (ISO 8601)

curl "https://api.santiauth.com/api/keys/folders?service_id=1" \
  -H "x-api-key: $SANTIAUTH_API_KEY"
200 OK
{
  "success": true,
  "data": [
    {
      "id": 123,
      "name": "Production Keys",
      "createdAt": "2026-04-30T15:37:35.645Z"
    },
    {
      "id": 124,
      "name": "Staging Keys",
      "createdAt": "2026-04-30T16:12:18.321Z"
    }
  ]
}

Get a folder

GET/api/keys/folders/{id}folders:read

Returns a single folder by ID for the authenticated owner. Use this when loading folder details, verifying access before reassigning resources, or confirming the current folder name in the UI.

Path parameters

  • idintegerrequired> 0

    Folder ID

Response fieldsinside data
  • idinteger

    Folder unique identifier

  • serviceIdinteger> 0

    Service the folder belongs to

  • namestring

    Folder name for organizing keys

  • createdAtstring

    Creation timestamp (ISO 8601)

curl "https://api.santiauth.com/api/keys/folders/3f2b8c1e-4d5a-4e6f-9a7b-8c9d0e1f2a3b" \
  -H "x-api-key: $SANTIAUTH_API_KEY"
200 OK
{
  "success": true,
  "data": {
    "id": 123,
    "name": "Production Keys",
    "createdAt": "2026-04-30T15:37:35.645Z"
  }
}

Rename a folder

PUT/api/keys/folders/{id}folders:write

Renames a folder.

Path parameters

  • idintegerrequired> 0

    Folder ID

Bodyapplication/json

  • namestring1–32 chars

    Updated folder name

Response fieldsinside data
  • idinteger

    Folder unique identifier

  • serviceIdinteger> 0

    Service the folder belongs to

  • namestring

    Folder name for organizing keys

  • createdAtstring

    Creation timestamp (ISO 8601)

curl -X PUT "https://api.santiauth.com/api/keys/folders/3f2b8c1e-4d5a-4e6f-9a7b-8c9d0e1f2a3b" \
  -H "x-api-key: $SANTIAUTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Staging Keys"
}'
200 OK
{
  "success": true,
  "data": {
    "id": 123,
    "name": "Staging Keys",
    "createdAt": "2026-04-30T15:37:35.645Z"
  }
}

Delete a folder

DELETE/api/keys/folders/{id}folders:write

Deletes the folder. Its keys are kept and simply become unfiled.

Path parameters

  • idintegerrequired> 0

    Folder ID

curl -X DELETE "https://api.santiauth.com/api/keys/folders/3f2b8c1e-4d5a-4e6f-9a7b-8c9d0e1f2a3b" \
  -H "x-api-key: $SANTIAUTH_API_KEY"
204 No Content
Empty body.

Key templates

Create a template

POST/api/key-templateskey-templates:write

Defines a key format for a service. With the body below, keys look like PREM-7K2QX-M4Z8R-P1N6W-C3T9B.

curl -X POST "https://api.santiauth.com/api/key-templates" \
  -H "x-api-key: $SANTIAUTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "service_id": 1,
  "name": "Premium",
  "prefix": "PREM",
  "segments": 4,
  "segmentLength": 5,
  "separator": "-",
  "charset": "alphanum"
}'
201 Created
{
  "success": true,
  "data": {
    "id": 1,
    "serviceId": 1,
    "name": "Premium",
    "prefix": "PREM",
    "segments": 4,
    "segmentLength": 5,
    "separator": "-",
    "charset": "alphanum",
    "validationRegex": null,
    "createdAt": "2026-09-30T12:00:00.000Z"
  }
}
FieldTypeNotes
service_idinteger, requiredService the template belongs to.
namestring, required1–128 chars.
prefixstringUp to 32 chars, prepended to every key.
segmentsinteger1–10. Default 3.
segmentLengthinteger1–16 characters per segment. Default 4.
separatorstringUp to 4 chars between segments. Default -.
charsetenumalphanum (A–Z 0–9), alpha, hex, numeric. Default alphanum.
validationRegexstringOptional regex every generated key must match.

List templates

GET/api/key-templateskey-templates:read

Templates of a service.

curl "https://api.santiauth.com/api/key-templates?service_id=1" \
  -H "x-api-key: $SANTIAUTH_API_KEY"

Preview a template

GET/api/key-templates/{id}/previewkey-templates:read

Generates one sample key with the template without saving anything — handy to check a format before you use it.

curl "https://api.santiauth.com/api/key-templates/3f2b8c1e-4d5a-4e6f-9a7b-8c9d0e1f2a3b/preview" \
  -H "x-api-key: $SANTIAUTH_API_KEY"
200 OK
{
  "success": true,
  "data": {
    "preview": "PREM-7K2QX-M4Z8R-P1N6W-C3T9B"
  }
}

Update a template

PATCH/api/key-templates/{id}key-templates:write

Send only the fields to change; they take the same values as on create. Keys that already exist keep their format.

curl -X PATCH "https://api.santiauth.com/api/key-templates/3f2b8c1e-4d5a-4e6f-9a7b-8c9d0e1f2a3b" \
  -H "x-api-key: $SANTIAUTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prefix": "VIP"
}'

Delete a template

DELETE/api/key-templates/{id}key-templates:write

Deletes the template. Keys generated with it are not affected.

curl -X DELETE "https://api.santiauth.com/api/key-templates/3f2b8c1e-4d5a-4e6f-9a7b-8c9d0e1f2a3b" \
  -H "x-api-key: $SANTIAUTH_API_KEY"