Create your first integration
For the shortest server-web walkthrough, use your first hosted login. This page covers configuration across all client types.
You need access to an Oathvera workspace, an application you can configure, and permission to manage its clients. All examples use placeholders; use values copied from your own workspace.
1. Choose your client
Section titled “1. Choose your client”Select Sandbox for initial integration work, wait until the environment is ready, then open Applications → Create application, name your product, and choose the first integration type.
| Console choice | Use it for | Authentication |
|---|---|---|
| Single-page web | JavaScript running in a browser | Authorization code + PKCE; no client secret. |
| Web with PKCE | A public web integration | Authorization code + PKCE; no client secret. |
| Mobile or desktop | A native application | Authorization code + PKCE; registered HTTPS or loopback callback. |
| Server web application | A backend handling a person’s sign-in | Authorization code + PKCE + client_secret_basic. |
| Machine to machine | A service or scheduled job | client_credentials + client_secret_basic. |
Choose Server web application when your server can protect the credential and keep tokens server-side. Add additional clients within the application when another integration needs its own configuration. The two public web choices do not add server credentials merely by having a backend.
2. Configure callbacks or service access
Section titled “2. Configure callbacks or service access”For human sign-in, register the exact callback URL your application handles. Register a post-logout URL if you will use hosted logout; choose a public signed-out page that does not automatically start login. Browser clients also need the exact allowed web origin for cross-origin token requests.
| Setting | Local server-web example | Meaning |
|---|---|---|
| Callback URL | http://localhost:3000/callback |
Your application’s code-exchange handler. |
| Post-logout URL | http://localhost:3000/ |
Optional destination after hosted logout. |
| Allowed web origin | http://localhost:3000 for a browser client |
Origin only: scheme, host and port, with no path. Server-web token calls do not use browser CORS. |
Use HTTPS for deployed callbacks. Local HTTP exceptions are for loopback development. localhost and 127.0.0.1 are different registrations; ports, paths and trailing slashes matter. Wildcard callbacks and arbitrary return URLs are not a substitute for registration. Current native support does not include custom URI schemes or Device Authorization Grant.
M2M clients do not use callbacks, allowed browser origins, login methods, user roles or branding. In their API permissions step, select an API and the exact required permissions. If no API exists, register one with a stable audience such as https://api.example.test/billing and permissions such as invoices:read. The identifier names the protected API; Oathvera does not deploy that API for you.
If you explicitly defer API setup, the M2M integration remains incomplete and cannot obtain a usable service token. No permissions are granted automatically.
3. Connect shared services
Section titled “3. Connect shared services”For human sign-in, configure Authentication in the workspace, then use the application’s Connections tab to inherit it or choose permitted methods. Configure shared branding under Branding → Hosted Login. Application Login Experience determines whether individuals, organization members, or both can enter.
Basic sign-in needs no API resource or role grant. Use registered openid, adding email profile when the product needs those identity fields. The console administrator account and an end-user account are separate.
If your application needs a protected API, configure API Access for its selected client. For human API access, also create the permission and role under Roles & permissions and assign the role to the user in the required application or organization context. See authorization.
4. Save integration values
Section titled “4. Save integration values”Open the application’s Quickstart and select the client and, when needed, its granted API. Copy:
| Value | Where it is used |
|---|---|
| Application ID | Administration and operational reference. It is not the OAuth client ID. |
| Client ID | Authorization, token requests and ID-token audience validation. |
| Issuer | Exact trusted authority for endpoints and token validation. |
| Redirect URI | The identical value in authorization and code exchange. |
| Scope | Space-separated registered identity scopes and explicitly granted API permissions. |
| Resource | The exact API audience, when requesting API access. |
| Client secret | Server-web and M2M clients only; save the one-time display into your server’s secret store. |
Keep secrets out of frontend environment bundles, source control, screenshots and logs. If the one-time secret is lost, rotate it; it cannot be retrieved again. Record the expiry and responsible operator.
5. Run the appropriate quickstart
Section titled “5. Run the appropriate quickstart”- Server web: redirect, callback validation, server session and revocation.
- Browser or native: public-client contract and library compatibility requirements.
- M2M: service token, API permission check and revocation.
The developer examples run locally. If configured with a production issuer, they still use that real workspace, users, grants and audit trail. A localhost callback does not create an isolated Oathvera environment. Use the workspace’s Sandbox environment with its own clients, credentials and issuer. Move to Production by registering and configuring a separate Production integration; changing only a label or callback is insufficient.
Continue with the production handoff and acceptance testing. Creating a client or seeing a successful branding preview alone does not establish a working integration.