Authentication

• Authentication
• Credential Authentication
  • How it works
  • Where to use it
• Secret Key Authentication
  • How it works
  • How your credentials are stored
  • When you must regenerate a secret key
  • Where to use it
• Comparing the Two
• Managing Secret Keys
• Next Steps

Authentication¶

The T3 API supports two authentication formats for most endpoints:

1. Credential authentication — a short-lived JWT obtained by exchanging your Metrc credentials at /v2/auth/credentials.
2. Secret key authentication — a long-lived opaque key that you generate once and then pass on every request.

Both formats produce the same effective access. Pick the one that matches how your integration runs.

Credential Authentication¶

How it works¶

1. Your client sends your Metrc username, password, and hostname (plus email for Colorado, or a one-time password for Michigan) to POST /v2/auth/credentials.
2. T3 logs in to Metrc on your behalf, caches the resulting session in Redis, and returns a JWT bearer token.
3. Your client sends the JWT with every subsequent request:

   Authorization: Bearer <jwt>
   

4. When the JWT expires, your client must repeat step 1 to get a new one.

Where to use it¶

• Interactive scripts you run manually from a laptop and that finish in one session.
• Notebook-driven analysis where you authenticate once at the top of the notebook and discard the token at the end.
• Postman / curl exploration of the API.

Credential authentication is the right default when you control the script end-to-end and don't want T3 to retain any version of your password.

Secret Key Authentication¶

How it works¶

1. You generate a secret key once via POST /v2/auth/secretkey, supplying your Metrc credentials.
2. T3 verifies the credentials by performing a real Metrc login, encrypts the credential blob at rest, and returns an opaque secret-key UUID.
3. Your client sends the secret key on every request, either in a header (preferred) or as a query parameter:

   X-T3-API-Key: <secret-key>
   

   or

   GET /v2/packages/active?secretKey=<secret-key>&licenseNumber=...
   

4. T3 resolves the key, re-uses the cached Metrc session when possible, and transparently re-authenticates against Metrc when the cached session expires — your integration never sees a Metrc-session-expired error.

How your credentials are stored¶

When you create a secret key, your Metrc credentials are encrypted at rest in T3's database. The plaintext is never logged and is only decrypted in-memory at request time to establish a Metrc session. The encryption key lives in T3's runtime environment and is rotated independently of the database.

That said: the credential blob is reversible by design — T3 has to be able to re-authenticate with Metrc on your behalf. The encryption protects against a database-only compromise, not against compromise of the running service.

When you must regenerate a secret key¶

Your secret key embeds a snapshot of the credentials you submitted at creation time. If any of the following change in Metrc, the existing secret key will stop working and you must create a new one:

• Password
• Email (Colorado only)
• Username
• One-time password (OTP) seed (Michigan only)

T3 does not automatically detect upstream credential changes — your secret key will start returning 401 Unauthorized after the change, and you'll need to delete the stale key and generate a fresh one.

Where to use it¶

• Long-running scripts (data pipelines, scheduled reports) that should not have to handle JWT refresh.
• Server-to-server integrations that benefit from one fixed credential rather than an in-memory token.
• Spreadsheet sync and other tools that need a stable URL with auth embedded.

Secret key authentication is the right default when your integration runs unattended or when re-authenticating periodically is a burden.

Comparing the Two¶

Managing Secret Keys¶

T3 provides a secret-key management page where you can create, list, and delete your keys. The page is backed by these endpoints:

The list response includes each key's createdAt, lastUsedAt (so you can identify dormant keys), and isEnabled flag.

When you delete a key, it stops authenticating immediately — there is no grace period.

Next Steps¶

• Generate your first secret key at the secret-key page.
• See Getting Started for an end-to-end script walkthrough.
• The T3 Python libraries handle both auth formats — use get_authenticated_client_or_error() from t3api-utils and the library will pick the right one based on what you've configured.
• Refer to the authentication endpoints in the interactive API documentation.