App IDs, secrets and access tokens

Application credentials in ALYT are tied to an application identity. You verify your developer account, create an app in the Dashboard, complete the app details required for the environment you want, then create DEV or LIVE credentials for that app. Verification does not issue an application secret, and Create an app before creating credentials is the required workflow. You exchange each app’s ID and secret for short-lived bearer tokens, rotate secrets with a seven-day overlap, and always pass tenantId explicitly when you call tenant-scoped APIs.

Credential types and App ID

ALYT supports these credential types:

Credential	App ID (client_id)	Access boundary
Existing legacy unbound DEV credential	Key id	Developer sandbox only
New DEV credential	definitionId	Developer sandbox only
LIVE credential	definitionId	Only that connector’s installed integrations

For new app-bound credentials, the App ID is the app’s definitionId. The Dashboard always shows the App ID for an application.

The app secret is the secret returned when you create or rotate credentials. ALYT shows that secret once. Store it in your server-side secret store when you receive it.

Create credentials

Use the Dashboard to create credentials for an app.

Required order

1. Verify your developer account.
2. Create an app in the Dashboard.
3. Complete the app’s listing and specification details.
4. Create DEV or LIVE credentials for that app.

Verification does not issue an application secret.

DEV credentials

POST /developers/keys requires definitionId for DEV credentials.

To create a new DEV credential, the latest app version must have complete:

• listing metadata
• specification
• guide
• release notes

A running runtime is not required at this stage. Provider test secrets are also not required for DEV credential creation.

DEV credentials act only in your developer sandbox. DEV credentials do not grant staff access, and household permissions remain narrower than staff where household access is relevant.

LIVE credentials

POST /developers/keys also requires definitionId for LIVE credentials.

To create LIVE credentials, you must own a connector that is approved or published. Approval unlocks credential creation. After approval, you deploy and confirm the release before publication.

LIVE credentials act only for that connector’s installed integrations. LIVE credentials do not grant broad account access beyond the installed connector boundary.

If you have a newer unpublished draft, it cannot change the public name or remove the existing version from the LIVE credential picker.

Exchange credentials for access tokens

Exchange your App ID and secret with:

POST /api/v1/developers/oauth/token

Supported client authentication methods:

• JSON body with client credentials
• form-encoded body with client credentials
• HTTP Basic credentials with a form body containing grant_type=client_credentials

You can send an optional space-separated scope to request a narrower token. Unknown scopes are refused.

The response includes:

• access_token
• token_type with value Bearer
• expires_in
• scope

Token lifetime is short: expires_in is at most 300 seconds. There is no refresh token.

The token response also sets:

• Cache-Control: no-store
• Pragma: no-cache

Using access tokens safely

Keep the app secret on the server side.

Do not put the secret in:

• browser code
• a mobile binary
• URLs
• source control
• a connector listing

Request a new access token before the current one expires.

Some developer portal API tools can prefill bearer authentication in the current browser tab when that tab has already seen your DEV secret, but that convenience does not change the security model. Treat the secret as a confidential server credential.

Authorization behavior

Machine credentials are checked on every API call against the current credential and account state. That means these changes take effect immediately, without waiting for token expiry:

• revocation
• expiry
• suspension
• reduced scopes
• removed installations

An explicit tenantId is required. Neither an App ID nor an access token selects a tenant implicitly.

Session-only account, review, and credential-management routes refuse machine credentials.

For LIVE credentials, access is still narrowed to the connector definition behind the credential, even when the token is otherwise valid.

Rotation and revocation

When you rotate credentials, ALYT creates a successor secret and keeps compatibility during a seven-day overlap. The seven-day overlap is capped by the predecessor’s earlier expiry, if it has one.

For app-bound credentials:

• the App ID stays the same
• the new secret replaces the old one in your secret store

If you revoke the predecessor, the overlap ends immediately.

For legacy unbound DEV credentials:

• rotation remains supported
• the successor gets a new App ID

If you still use a legacy unbound DEV credential, copy both the new App ID and the new secret after rotation, or move to an app-bound identity if you need a persistent App ID.

No new unbound ordinary DEV credential can be created.

Suspension, deprecation, and installed homes

If a connector is deprecated, new installations stop, but existing LIVE credentials can still obtain tokens for homes that already installed that connector.

Suspension or credential revocation explicitly stops access.

Environment and access boundaries

DEV credentials act in the developer sandbox only.

LIVE credentials act only for the developer’s own installed connector.

Household permissions are narrower than staff, but this mainly matters for user-session routes rather than machine credentials. For machine-to-machine calls, follow the connector and tenant boundaries described above.

Cloud-dependent connectors require the provider and network. Local functions can keep working during a cloud outage, but do not assume a cloud connector can work when its cloud path is unavailable.

Standards note

This flow uses the confidential-client pattern from OAuth 2.0 client credentials exchange. It is a compatible exchange with limited token lifetime and scope narrowing. It does not claim refresh tokens, asymmetric client authentication, enterprise SSO, organization roles, or environment-specific application ownership.