How Oathvera fits into your application
Oathvera authenticates people and workloads. Your application remains responsible for its product data, business rules and enforcement of access decisions.
Ownership
Section titled “Ownership”| Object | Owns or controls |
|---|---|
| Workspace | Console ownership and two isolated identity environments: Production and Sandbox. |
| Environment | Its own user directory, credentials and factors, authentication baseline, social providers, Universal Login branding, hostnames, applications and API catalog. |
| Application | A product consuming those services; user admission, application authentication selections, organization requirements, roles and permissions. |
| Client | A particular integration of an application: browser, mobile, server web or backend service. Each has a client ID and its own protocol settings and grants. |
| API resource | A protected API identified by an audience/resource identifier and a catalog of permission keys. |
| Client API grant | The API and maximum permissions a particular client can request. |
| Organization | The business context for membership, enterprise identity connections and organization-specific access. Current enterprise records remain application-bound. |
One product can have a web client, an iOS client and a billing-job client under one application. Register them separately so callbacks, credentials, permissions and revocation can be managed independently.
Users belong to one environment in the workspace. Access to an application is a separate relationship. Creating a user does not automatically assign roles; granting a client API access does not authorize every user of that client. Suspending workspace identity can affect all its applications, while removing application access is narrower.
Four layers of authentication
Section titled “Four layers of authentication”Keep these decisions separate when designing an integration:
- Identity source: an Oathvera account, a social provider, an enterprise identity provider, or a workload client.
- Factor and assurance: password, email proof, passkey, TOTP, or security key; recovery has its own controlled flow.
- Protocol: authorization code with PKCE for a person; client credentials for an M2M service.
- Presentation: workspace Universal Login, including branding and the authentication domain.
An enterprise OIDC connection is an upstream identity source. Your application still uses Oathvera’s authorization endpoint and receives Oathvera tokens. An M2M client uses its own identity and has no Universal Login screen.
Shared defaults and application rules
Section titled “Shared defaults and application rules”Select Production or Sandbox, then configure shared authentication and branding for that workspace environment. An application can inherit the authentication defaults or select allowed methods and stronger requirements. It cannot bypass a workspace security requirement. Existing application-specific social-provider configurations retain their compatibility behavior; do not assume a workspace change replaces every legacy override.
Enterprise SSO connections are currently bound to an application and organization. They are not freely shareable across all workspace applications. See enterprise SSO.
Issuers and identity keys
Section titled “Issuers and identity keys”Copy the exact issuer from your application’s integration details. Its shape is:
https://<authentication-host>/t/<tenant-id>The host may be Oathvera’s generated workspace hostname or your connected custom hostname. The tenant path is part of the issuer. Preserve the complete string; do not add a trailing slash or replace the hostname based on an incoming request.
Use the validated (iss, sub) pair as the external identity key in your application. Subjects are pairwise: the current implementation derives them for the client and authentication hostname. Two clients in the same workspace can receive different subjects for the same person. A hostname change can also change the subject. Do not use email matching to merge accounts or assume an Oathvera console user ID equals an OIDC subject.
Tokens and sessions
Section titled “Tokens and sessions”An ID token is an ES256-signed JWT describing a completed human sign-in for a client. An access token is opaque and authorizes use at its intended resource. A refresh token rotates and can obtain replacement human access tokens within the remaining authority and lifetime. M2M clients receive only an access token.
Your application’s session, Oathvera’s hosted sign-in session and any upstream provider session are separate. Logging out of one does not promise global logout from every application or provider. See sessions and credentials.
Console administrators use a separate management sign-in. Their console account or console API key is not an end-user token for your product.
Production and Sandbox
Section titled “Production and Sandbox”Select the environment before creating an application. Each environment has a separate identity database, runtime, tenant ID, client registrations, credentials and sign-in state. Sandbox starts empty; Production identities and secrets are not copied into it. The console login manages both environments, but it is not an end-user session in either one. The selector is tab-local, so two console tabs can manage different environments.
Copy the issuer and client ID from the selected environment. New generated hosts use readable random names such as your assigned authentication hostname. Production and Sandbox receive separate names in the same format; the hostname does not indicate the environment. Existing issuers, including r-<id>.oathvera.app, s-<id>.oathvera.app and older readable names, keep their original host and tenant path. Never construct a Sandbox issuer by editing the Production URL. A pending environment becomes usable only after provisioning and runtime verification finish.