API Reference

Complete reference for all iuv.one OIDC API endpoints.

Base URL

https://iuv.one

POST/api/oauth/token

Token Endpoint

Exchange authorization codes for tokens or refresh existing tokens.

Authorization Code Grant

Parameter	Type	Required	Description
`grant_type`	string	Yes	Must be "authorization_code"
`code`	string	Yes	The authorization code received from the authorize endpoint
`redirect_uri`	string	Yes	Must match the redirect_uri used in the authorization request
`client_id`	string	Yes	Your application's client ID
`client_secret`	string	No	Required for confidential clients
`code_verifier`	string	No	Required if PKCE was used in authorization request

Example Request

bash

curl -X POST https://iuv.one/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret"

Success Response (200 OK)

json

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

Refresh Token Grant

Parameter	Type	Required	Description
`grant_type`	string	Yes	Must be "refresh_token"
`refresh_token`	string	Yes	A valid refresh token
`client_id`	string	Yes	Your application's client ID
`client_secret`	string	No	Required for confidential clients

GET/api/oauth/userinfo

UserInfo Endpoint

Retrieve user profile information using an access token.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer token (e.g., "Bearer {access_token}")

Example Request

bash

curl https://iuv.one/api/oauth/userinfo \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Success Response (200 OK)

json

{
  "sub": "user_123456789",
  "name": "John Doe",
  "email": "john@example.com",
  "email_verified": true,
  "picture": "https://example.com/avatar.jpg"
}

GET/api/oauth/jwks

JWKS Endpoint

Retrieve the JSON Web Key Set for verifying token signatures.

Example Request

bash

curl https://iuv.one/api/oauth/jwks

Success Response (200 OK)

json

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "key-id-1",
      "use": "sig",
      "alg": "RS256",
      "n": "0vx7agoebGc...",
      "e": "AQAB"
    }
  ]
}

POST/api/oauth/revoke

Token Revocation Endpoint

Revoke an access token or refresh token.

Parameters

Parameter	Type	Required	Description
`token`	string	Yes	The token to revoke (access or refresh token)
`token_type_hint`	string	No	"access_token" or "refresh_token"
`client_id`	string	Yes	Your application's client ID
`client_secret`	string	No	Required for confidential clients

Example Request

bash

curl -X POST https://iuv.one/api/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=YOUR_TOKEN" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret"

Success Response (200 OK)

Returns an empty response body on success. The token is revoked regardless of whether it was valid.

GET/.well-known/openid-configuration

Discovery Endpoint

OpenID Connect discovery document with all configuration details.

Example Request

bash

curl https://iuv.one/.well-known/openid-configuration

Response

Returns the full OpenID Connect configuration. See the configuration section for the complete response format.

Error Responses

All endpoints return standard OAuth 2.0 error responses:

json

{
  "error": "invalid_request",
  "error_description": "The request is missing a required parameter"
}

Error Code	Description
`invalid_request`	Missing or invalid parameter
`invalid_client`	Client authentication failed
`invalid_grant`	Invalid authorization code or refresh token
`unauthorized_client`	Client not authorized for this grant type
`unsupported_grant_type`	Grant type not supported
`invalid_scope`	Invalid or unknown scope

Rate Limiting

API requests are rate limited to ensure fair usage. Current limits:

Token endpoint: 100 requests per minute per client
UserInfo endpoint: 1000 requests per minute per token
Revocation endpoint: 100 requests per minute per client

When rate limited, the API returns a 429 Too Many Requests response with a Retry-After header.