Import tokens from a file

Bulk import tokens from CSV, XLSX, JSON, or YAML files. This is the fastest way to migrate from spreadsheets or to load an export from another system.

Open Import tokens from the dashboard and pick the file card, or use the REST API.

The Import tokens modal: file upload plus integration providers.

Formats and fields

Required fields:

• name (1-255 characters), category, type, and expiresAt for the dashboard file uploader.
• category is one of cert, key_secret, license, general. Use the type that belongs to the category. The add and edit forms offer only these pairs, and editing an asset whose type does not belong to its category is rejected:
  • cert: ssl_cert, tls_cert, code_signing, client_cert
  • key_secret: api_key, secret, password, encryption_key, ssh_key
  • license: software_license, service_subscription, domain_registration
  • general: other, document, membership general is a category, not a type; use other.
• expiresAt uses YYYY-MM-DD. To import a Never expires record through the dashboard, use the sentinel date 2099-12-31. Rows with an empty or missing date are excluded from the upload preview. The REST API can default an omitted or null expiry to Never expires; the dashboard uploader has stricter requirements.

Optional fields:

• section, domains, location, used_by, contacts, description, notes, privileges, last_used, contact_group_id, contact_group_ids
  • contact_group_ids: one or more workspace contact group IDs (JSON/YAML array, or in CSV/XLSX a ; or , separated list). When present, it wins over contact_group_id.
  • contact_group_id: legacy singular ID; still accepted when contact_group_ids is omitted. Omit both to leave membership unset (workspace default at alert time).
• Certificates: issuer, serial_number, subject
• Keys: key_size (positive integer), algorithm
• Licenses: license_type, vendor, cost, renewal_url, renewal_date

The workspace is taken from your current selection, so the file does not include a workspace_id.

tip

Include a location column for reliable deduplication: re-importing a row with the same name + location updates the existing token instead of creating a duplicate.

Before uploading, select the destination workspace. After parsing, compare the preview row count with your file, select the intended rows, then import. Confirm the resulting assets and dates in Asset Inventory. Missing required fields can exclude rows before they reach the API. A file with wrong column names, or an empty file, shows no error: the preview is empty and the button reads "Import 0 selected". Check the header row. The dashboard imports row by row from your browser, so keep the dialog open until it reports the result. Large files take minutes, not seconds. If an import stops part-way, run the same file again: rows with the same name and location update the existing asset instead of creating a duplicate.

The dates below are illustrative. For an alert-delivery check, choose a future expiry that reaches one of your configured thresholds; already-passed thresholds are suppressed on import.

CSV / XLSX example

name,category,type,expiresAt,section,domains,privileges,last_used
Example TLS Cert,cert,ssl_cert,2030-01-31,"prod, public",example.com,,
API Gateway Key,key_secret,api_key,2030-12-15,"prod, api",api.example.com,"read, write",2025-06-10

JSON example

[
  {
    "name": "Example API Key",
    "category": "key_secret",
    "type": "api_key",
    "expiresAt": "2030-05-15",
    "section": "backend, internal",
    "domain": "service.example.com",
    "privileges": "read:all, write:logs",
    "last_used": "2025-11-20"
  }
]

YAML example

tokens:
  - name: Example TLS Cert
    category: cert
    type: ssl_cert
    expiresAt: 2030-01-31
    section: prod, external
    privileges: 'read, sign'
    last_used: 2025-10-15
    domains:
      - example.com
      - www.example.com
    issuer: "Let's Encrypt"
    location: /etc/ssl/certs
    used_by: edge-proxy

File limits

A file may be at most 5 MB and 5000 rows. A larger file is refused in the browser before anything is uploaded, with a message such as "This file is 6.2 MB. The limit is 5 MB. Split it into smaller files and import them one at a time." or "This file has 6000 rows. The limit is 5000 rows per file. Split it into smaller files and import them one at a time." The same limits apply when you import from the setup wizard. Rows that match an existing token on name and location update that token.

Behavior on import

• Deduplication: rows matching an existing token on name + location update that token. See Automatic deduplication.
• Alert catch-up: alerts for thresholds that have already passed are suppressed to prevent notification storms; alerting resumes at the next future threshold.