API Reference

Discovery Endpoints

These endpoints expose server metadata for automated client configuration.

Method	Endpoint	Description
GET	/.well-known/openid-configuration	OpenID Connect Discovery (RFC 8414)
GET	/.well-known/oauth-authorization-server	OAuth 2.0 Authorization Server Metadata (RFC 8414)
GET	/.well-known/oauth-protected-resource	Protected Resource Metadata (RFC 9728)
GET	/	Service info and endpoint listing

Example: OpenID Configuration

curl https://auth.credplatform.com/.well-known/openid-configuration

{
  "issuer": "https://auth.credplatform.com",
  "authorization_endpoint": "https://auth.credplatform.com/oauth/auth",
  "token_endpoint": "https://auth.credplatform.com/oauth/token",
  "userinfo_endpoint": "https://auth.credplatform.com/oauth/me",
  "jwks_uri": "https://auth.credplatform.com/oauth/jwks",
  "scopes_supported": ["openid", "profile", "email", "offline_access"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "claims_supported": ["sub", "iss", "aud", "exp", "iat", "email", "email_verified", "name", "preferred_username"]
}

---

OAuth 2.0 / OIDC Endpoints

These are served by oidc-provider under the /oauth path.

Method	Endpoint	Description
GET	/oauth/auth	Authorization endpoint — initiates the code flow
POST	/oauth/token	Token endpoint — exchanges code for tokens
GET	/oauth/me	UserInfo endpoint
GET	/oauth/jwks	JSON Web Key Set (public keys for token verification)
POST	/oauth/token/introspection	Token introspection (RFC 7662)
POST	/oauth/token/revocation	Token revocation (RFC 7009)

Authorization Request

GET /oauth/auth?
  response_type=code&
  client_id=your-client-id&
  redirect_uri=http://localhost:8080/callback&
  scope=openid%20profile%20email&
  code_challenge={codeChallenge}&
  code_challenge_method=S256&
  state={randomState}

Note

PKCE is required for all authorization requests. Requests without code_challenge will be rejected.

Token Exchange

curl -X POST https://auth.credplatform.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code={authorization_code}" \
  -d "redirect_uri=http://localhost:8080/callback" \
  -d "client_id=your-client-id" \
  -d "client_secret=your-client-secret" \
  -d "code_verifier={codeVerifier}"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "scope": "openid profile email"
}

UserInfo

curl https://auth.credplatform.com/oauth/me \
  -H "Authorization: Bearer {access_token}"

Response:

{
  "sub": "42",
  "email": "user@example.com",
  "email_verified": true,
  "preferred_username": "user@example.com",
  "userRole": "admin"
}

---

Dynamic Client Registration (RFC 7591)

Available when OAUTH_DYNAMIC_REGISTRATION=true.

Method	Endpoint	Description
POST	/oauth/reg	Register a new client
GET	/oauth/reg/:clientId	Read client registration
PUT	/oauth/reg/:clientId	Update client registration
DELETE	/oauth/reg/:clientId	Delete client registration

Register a Client

curl -X POST https://auth.credplatform.com/oauth/reg \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My Application",
    "redirect_uris": ["https://myapp.com/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "client_secret_basic"
  }'

Response:

{
  "client_id": "client_abc123...",
  "client_secret": "generated-secret",
  "client_name": "My Application",
  "redirect_uris": ["https://myapp.com/callback"],
  "registration_access_token": "...",
  "registration_client_uri": "https://auth.credplatform.com/oauth/reg/client_abc123..."
}

Tip

Registration access tokens are rotated on every management operation (GET/PUT/DELETE) for security.

---

Login / Consent Interaction

Server-rendered pages for user authentication during the OAuth flow.

Method	Endpoint	Description
GET	/login/:uid	Display login or consent form
POST	/login/:uid/submit	Submit email/password credentials
POST	/login/:uid/confirm	Confirm consent (grant scopes)
POST	/login/:uid/abort	Cancel the authorization request

All POST endpoints are protected by CSRF guard. The CSRF token is included in the rendered form.

---

REST Authentication Endpoints

Direct JWT-based authentication (independent of OIDC flows). Useful for service-to-service or API-first integrations.

Method	Endpoint	Description
POST	/auth/login	Authenticate with email/password, receive JWT
GET	/auth/me	Get current user profile (requires Bearer token)

Login

curl -X POST https://auth.credplatform.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "secret"}'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "42",
    "email": "user@example.com",
    "emailVerified": true,
    "userRole": "admin"
  }
}

Get Profile

curl https://auth.credplatform.com/auth/me \
  -H "Authorization: Bearer {token}"

Response:

{
  "id": "42",
  "email": "user@example.com",
  "emailVerified": true,
  "userRole": "admin"
}

---

PKCE Flow (Complete Example)

1. Generate PKCE Challenge

const crypto = require('crypto');

const codeVerifier = crypto.randomBytes(32).toString('base64url');
const codeChallenge = crypto
  .createHash('sha256')
  .update(codeVerifier)
  .digest('base64url');

2. Redirect to Authorization

GET /oauth/auth?
  response_type=code&
  client_id=test-client&
  redirect_uri=http://localhost:8080/callback&
  scope=openid%20profile%20email&
  code_challenge={codeChallenge}&
  code_challenge_method=S256&
  state={randomState}

3. User Logs In and Consents

The user is redirected to /login/:uid where they enter credentials and approve the requested scopes.

4. Exchange Code for Tokens

curl -X POST http://localhost:3000/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code={authorization_code}" \
  -d "redirect_uri=http://localhost:8080/callback" \
  -d "client_id=test-client" \
  -d "client_secret=test-secret" \
  -d "code_verifier={codeVerifier}"

5. Use the Access Token

curl http://localhost:3000/oauth/me \
  -H "Authorization: Bearer {access_token}"

---

JWT Access Token Claims

Access tokens issued by CRED Auth include these claims:

Claim	Description
sub	User ID
iss	Issuer (OAUTH_ISSUER)
aud	Audience (resource indicator or issuer)
exp	Expiration timestamp
iat	Issued-at timestamp
client_id	The client that requested the token
scope	Granted scopes
email	User's email address
userRole	User's role in the platform

---

Supported Scopes

Scope	Claims Included
openid	sub
profile	name, family_name, given_name, preferred_username, userRole
email	email, email_verified
offline_access	Enables refresh token issuance