Token handling

An access token is a bearer credential: whoever holds it can act as the authorizing user within the granted scopes. Homa treats every token as a secret of the highest sensitivity.

• Tokens are encrypted before they are written, using a key managed outside the application database.
• A database backup or a leaked dump therefore contains ciphertext, not usable credentials.
• The encryption key is supplied through the environment and is never committed to version control.
• Decryption happens only in the server process that needs to make a call, and the plaintext is never persisted.

Every token belongs to exactly one tenant. Isolation is enforced at the query level so a bug in application logic cannot read across tenant boundaries.

1. Resolve the tenant from the authenticated session, never from a client-supplied parameter.
2. Include the tenant identifier in the WHERE clause of every token read.
3. Reject any request whose target asset does not belong to the resolved tenant.
4. Record the tenant identifier on every audit log entry.

Tokens are time-limited. Homa refreshes proactively where the platform supports it and degrades cleanly where it does not.

Short-lived token

Issued immediately after the code exchange. Exchanged for a long-lived token straight away; never used for ongoing work.

Long-lived token

Used for routine API access. Refreshed ahead of expiry so a customer never sees an interruption caused by timing alone.

Expired token

Refresh is attempted once. On failure the connection is marked as needing attention and the customer is prompted inside Homa CRM.

• Replace a stored token in a single transaction so a failure cannot leave a tenant with no usable credential.
• Keep the previous value only until the replacement is confirmed working, then delete it.
• Rotate the app secret and the webhook verify token on a schedule, and immediately after any suspected exposure.
• Rotating the app secret invalidates in-flight code exchanges; schedule it during a low-traffic window.

Revocation must be immediate and complete. A token that is no longer needed is deleted rather than left dormant.

1. Delete the encrypted token record.
2. Mark the connection inactive so no worker picks it up.
3. Cancel queued outbound jobs that depend on it.
4. Write an audit entry recording the actor, the reason and the timestamp.

• Redact credential-shaped values at the logger, so a careless call site cannot leak one.
• Never attach a token to an error report, a performance trace or an analytics event.
• Do not include tokens in exception messages, which frequently reach third-party monitoring tools.
• Log a correlation identifier instead, and join to secure storage when investigating.