Identvia
Get started
Developer documentation

Build with Identvia

Identvia speaks standard OAuth 2.1 and OpenID Connect, so the auth library you already use will work. This page is the whole integration: register an app, send the user to Identvia, swap the code for tokens, read the profile. Then, optionally, give AI agents scoped passes with the REST API or MCP.

1. Register your app

Sign in, open the Developer console, and create an application. Note your client_id and the one-time client_secret. Register your callback URL exactly; codes are only sent to listed URIs.

2. Send the user to Identvia (with PKCE)

// 1) Generate a random code_verifier (43–128 chars). Keep it in the session. // 2) code_challenge = base64url( SHA256(code_verifier) ) — no padding. // 3) Redirect the browser: https://allowia.com/authorize ?client_id=YOUR_CLIENT_ID &redirect_uri=https://yourapp.com/callback &response_type=code &scope=openid profile email &code_challenge=CHALLENGE&code_challenge_method=S256 &state=RANDOM_CSRF_VALUE

The user signs in at Identvia (never at your site), reviews a consent screen listing exactly what you requested, and returns to your redirect URI with a single-use code that expires in 10 minutes.

3. Exchange the code for tokens

POST https://allowia.com/token Content-Type: application/x-www-form-urlencoded Authorization: Basic base64(client_id:client_secret) grant_type=authorization_code&code=CODE &redirect_uri=https://yourapp.com/callback &code_verifier=YOUR_VERIFIER
{ "access_token": "eyJ…", "id_token": "eyJ…", "refresh_token": "…" , "token_type": "Bearer", "expires_in": 3600, "scope": "openid profile email" }

Access tokens are JWTs signed with the platform secret (HS256 in v1). Refresh tokens rotate on every use and can be revoked by the user at any time from Connected apps. Discovery document: https://allowia.com/discovery (also at /.well-known/openid-configuration on Apache).

4. Read the user profile

GET https://allowia.com/api?action=me Authorization: Bearer ACCESS_TOKEN { "sub": "42", "name": "…", "email": "…", "timezone": "America/Los_Angeles" }

Only the fields covered by the granted scopes are returned. Add the preferences scope to receive the user's shareable preferences object.

Minimal PHP client (no libraries)

<?php // callback.php $tokens = http_post('https://allowia.com/token', [ 'grant_type' => 'authorization_code', 'code' => $_GET['code'], 'redirect_uri' => 'https://yourapp.com/callback', 'code_verifier' => $_SESSION['pkce_verifier'], 'client_id' => 'YOUR_CLIENT_ID', 'client_secret' => 'YOUR_CLIENT_SECRET', ]); $user = http_get('https://allowia.com/api?action=me', ['Authorization: Bearer ' . $tokens['access_token']]); // $user is the signed-in person. Create your local session.

A runnable copy of this client lives in the demo-client folder of the Identvia package. Point it at your install and sign in end-to-end in two minutes.

Scopes

ScopeWhat the holder receives
openidSign you in
profileRead your name, picture and timezone
emailRead your email address
preferencesRead your saved preferences (tone, language, choices you opted to share)
agent.actLet an AI agent act for you within limits you set

Agent Passes (REST)

Users create Agent Passes in Identvia > AI Agents & approvals and hand the token to one agent. The agent never receives the user's password or a session token.

GET https://allowia.com/api?action=agent_me Authorization: Bearer idv_agent_… POST https://allowia.com/api?action=request_approval // needs agent.act scope Authorization: Bearer idv_agent_… { "title": "Book flight to Denver", "detail": "UA 1842, $214, Thu 9:05 AM" } → 201 { "id": "apr_…", "status": "pending" } GET https://allowia.com/api?action=approval&id=apr_… → { "status": "approved" | "denied" | "pending" | "expired" }

MCP server

Endpoint: https://allowia.com/mcp — stateless JSON-RPC over POST, designed to run on ordinary shared hosting. Send the Agent Pass as a bearer token. Tools: identvia.get_profile, identvia.request_approval, identvia.check_approval.

POST https://allowia.com/mcp Authorization: Bearer idv_agent_… { "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

In Claude / MCP client config, register it as a remote HTTP server with that URL and an Authorization header containing the Agent Pass.

Security model