OAuth 2.1 / OIDC Integration

Overview

OAuth 2.1 is the latest evolution of the OAuth framework. It consolidates security best practices from OAuth 2.0 extensions into a single specification, removing legacy flows that are no longer considered secure.

Supported grant types: authorization_code and refresh_token.

OIDC Discovery

The OpenID Connect Discovery endpoint publishes all configuration your client library needs to auto-configure itself — issuer, endpoints, supported scopes, signing algorithms, and more. Most OIDC client libraries accept a single discovery URL and handle the rest.

GET/.well-known/openid-configurationPublic

OpenID Connect Discovery document. Returns all supported endpoints, scopes, and algorithms.

RequestResponse

cURLJavaScriptPythonGoPHP

curl https://id.vyntech.com.au/.well-known/openid-configuration

Authorization Code Flow with PKCE

This is the only supported flow. It works for all client types — web apps, SPAs, mobile apps, and CLI tools. PKCE (Proof Key for Code Exchange) protects against authorization code interception attacks.

// JavaScript
const array = new Uint8Array(32);
crypto.getRandomValues(array);
const codeVerifier = btoa(String.fromCharCode(...array))
  .replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");

const digest = await crypto.subtle.digest("SHA-256",
  new TextEncoder().encode(codeVerifier));
const codeChallenge = btoa(String.fromCharCode(...new Uint8Array(digest)))
  .replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");

GET https://id.vyntech.com.au/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=openid profile email offline_access roles
  &state=RANDOM_STATE_VALUE
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256

GET https://yourapp.com/callback
  ?code=AUTH_CODE_HERE
  &state=RANDOM_STATE_VALUE

5

Exchange code for tokens

POST the authorization code along with the original code_verifier to the token endpoint. The server verifies that SHA-256(code_verifier) matches the code_challenge sent in Step 2.

POST/oauth/tokenPublic

Exchange authorization code for access, ID, and refresh tokens.

RequestResponse

cURLJavaScriptPythonGoPHP

curl -X POST https://id.vyntech.com.au/oauth/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=authorization_code" \ -d "code=AUTH_CODE_HERE" \ -d "redirect_uri=https://yourapp.com/callback" \ -d "client_id=YOUR_CLIENT_ID" \ -d "code_verifier=YOUR_CODE_VERIFIER"

// JavaScript — verify with jose library
import { createRemoteJWKSet, jwtVerify } from "jose";

const JWKS = createRemoteJWKSet(
  new URL("https://id.vyntech.com.au/.well-known/jwks.json")
);

const { payload } = await jwtVerify(tokens.id_token, JWKS, {
  issuer: "https://id.vyntech.com.au",
  audience: "YOUR_CLIENT_ID",
});

console.log(payload.sub);   // user ID
console.log(payload.email); // user email
console.log(payload.roles); // ["admin", "member"]

Scopes

Scopes determine what information and capabilities the tokens will include. Request them as a space-separated list in the scope parameter.

Token Exchange

Exchange an authorization code for tokens. This is the same endpoint shown in Step 5 above, documented here with full request/response details for reference.

POST/oauth/tokenPublic

Exchange authorization code for tokens (grant_type=authorization_code).

RequestResponse

cURLJavaScriptPythonGoPHP

curl -X POST https://id.vyntech.com.au/oauth/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=authorization_code" \ -d "code=AUTH_CODE_HERE" \ -d "redirect_uri=https://yourapp.com/callback" \ -d "client_id=YOUR_CLIENT_ID" \ -d "code_verifier=YOUR_CODE_VERIFIER"

Request Body

{
  "grant_type": "authorization_code",
  "code": "AUTH_CODE_HERE",
  "redirect_uri": "https://yourapp.com/callback",
  "client_id": "YOUR_CLIENT_ID",
  "code_verifier": "YOUR_CODE_VERIFIER"
}

Userinfo Endpoint

Fetch the authenticated user's profile information using the access token. The claims returned depend on the scopes granted during authorization.

GET/oauth/userinfo🔒 Auth

Get the current user's profile claims using a valid access token.

RequestResponse

cURLJavaScriptPythonGoPHP

curl https://id.vyntech.com.au/oauth/userinfo \ -H "Authorization: Bearer ACCESS_TOKEN"

Refresh Token

Use the refresh token to obtain a new access token without requiring the user to re-authenticate. Refresh tokens are rotated on every use — the old token is immediately invalidated and a new one is returned.

POST/oauth/tokenPublic

Refresh an access token using a valid refresh token (grant_type=refresh_token).

RequestResponse

cURLJavaScriptPythonGoPHP

curl -X POST https://id.vyntech.com.au/oauth/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=refresh_token" \ -d "refresh_token=rt_01H8XYZABC123..." \ -d "client_id=YOUR_CLIENT_ID"

Client Registration

Register an OAuth client to receive a client_id. Each client has a name, one or more redirect URIs, and a list of allowed scopes. Clients are scoped to a tenant.

POST/oauth/clients🔒 Auth

Register a new OAuth client for your tenant.

RequestResponse

cURLJavaScriptPythonGoPHP

curl -X POST https://id.vyntech.com.au/oauth/clients \ -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "My Web App", "redirect_uris": [ "https://myapp.com/callback", "http://localhost:3000/callback" ], "scopes": ["openid", "profile", "email", "offline_access", "roles"] }'

Request Body

{
  "name": "My Web App",
  "redirect_uris": [
    "https://myapp.com/callback",
    "http://localhost:3000/callback"
  ],
  "scopes": ["openid", "profile", "email", "offline_access", "roles"]
}

ID Token Claims

The id_token is a JWT (JSON Web Token) signed with EdDSA (Ed25519). It contains claims about the authenticated user. The exact claims depend on the scopes requested.

Example decoded payload:

{
  "sub": "usr_01H8ABC123",
  "iss": "https://id.vyntech.com.au",
  "aud": "cli_01H8XYZ789",
  "exp": 1700000900,
  "iat": 1700000000,
  "nonce": "n-0S6_WzA2Mj",
  "email": "jane@acme-corp.com",
  "name": "Jane Smith",
  "tid": "tnt_01H7XYZ789",
  "roles": ["admin", "member"]
}

Best Practices

What's Next