Sionyw Account API Documentation

Welcome to the API documentation for Sionyw account management. This document provides details on how to interact with our API endpoints. All post requests and responses are in JSON format, unless otherwise specified.

You can also download this documentation in markdown format for easier reading or integration with other tools such as LLM here.

OAuth API

Sionyw Account supports OAuth 2.1 and OpenID Connect 1.0 protocols for secure authorization and authentication. You can use OAuth to allow users to authenticate with Sionyw Account and authorize your application to access their data.

npm install openid-client

import * as oauth from 'openid-client';

// 1. Discover the OpenID provider configuration
const issuer = new URL('https://account.sionyw.com');
const config = await oauth.discovery(issuer, 'YOUR_CLIENT_ID', 'YOUR_CLIENT_SECRET');

// 2. Generate PKCE parameters for security
const code_verifier = oauth.randomPKCECodeVerifier();
const code_challenge = await oauth.calculatePKCECodeChallenge(code_verifier);

// 3. Generate authorization URL
const authorizationUrl = oauth.buildAuthorizationUrl(config, {
  redirect_uri: 'http://localhost:3000/callback',
  scope: 'openid risuai',
  code_challenge,
  code_challenge_method: 'S256',
});

// 4. Redirect user to authorizationUrl...
// After user authorizes, they'll be redirected to your callback URL

// 5. In your callback handler, extract the authorization response
const currentUrl = new URL(req.url); // Your callback URL with code
const params = oauth.validateAuthResponse(config, currentUrl, oauth.expectNoState);

if (oauth.isOAuth2Error(params)) {
  throw new Error(`OAuth error: ${params.error} - ${params.error_description}`);
}

// 6. Exchange the code for tokens
const tokenResponse = await oauth.authorizationCodeGrant(config, currentUrl, {
  pkceCodeVerifier: code_verifier,
  expectedNonce: oauth.expectNoNonce,
});

const tokenSet = await oauth.processAuthorizationCodeResponse(config, tokenResponse);

// 7. Access token is now available
console.log('Access Token:', tokenSet.access_token);
console.log('Token expires in:', tokenSet.expires_in, 'seconds');

// Example: Get user information using openid-client
const userInfoResponse = await oauth.userInfoRequest(config, tokenSet.access_token);
const userInfo = await userInfoResponse.json();
console.log('User Info:', userInfo);

// Example: Make a request to any protected API endpoint
// You can use the standard fetch API with the access token
const apiResponse = await fetch('https://api.example.com/api/example_url', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${tokenSet.access_token}`,
    'Content-Type': 'application/json'
  }
});

const data = await apiResponse.json();
console.log('API Response:', data);

Quick Start - Without Library

You can also interact with the OAuth endpoints directly using HTTP requests. we don't provide code examples here, since there are many OAuth 2.0 examples (which is also applicable to OAuth 2.1 if it supports PKCE) available online for various programming languages and frameworks. You can refer to the official OAuth 2.0 documentation at https://oauth.net/2/ for general guidance on implementing the OAuth 2.0 authorization code flow.

Scopes

The following scopes are supported for all clients:

• risuai: Access to Risuai API endpoints.
• openid: Request an ID token for OpenID Connect authentication.
• refresh_token: Request a refresh token to obtain new access tokens without user re-authentication.

The following scopes are uses to define Oauth versions, clients can request these scopes to indicate which Oauth version they are using:

• oauth_21_draft_14: Indicates the client is using Oauth 2.1 draft-14 protocol.
• oauth_21_latest: Indicates the client is using the latest OAuth 2.1 protocol which the server supports. this is the default if no Oauth version scope is specified. currently this will act the same as oauth_21_draft_14.

Additional scopes that is only available to trusted clients, which should be requested by contacting support and getting approval:

• master: Access to master-level administrative endpoints.
• confidential_client: Indicates the client is a confidential client mentioned in Oauth 2.1 specification, which can securely store client credentials, removing some restrictions applied to other clients.
• no_consent: Allows the client to skip user consent prompt during authorization unless its required by law like GDPR. requires confidential_client scope to be granted.
• no_refresh_token_rotation: Disables refresh token rotation for the client, allowing reuse of refresh tokens. requires confidential_client scope to be granted.

Additional scopes that is internally used and cannot be requested by clients, which can be auto granted based on the client authentication method:

• oauth: Can be auto granted when client is logged in using OAuth API
• direct: Can be auto granted when client is logged in using direct login
• viaapikey: Can be auto granted when client is logged in using API key

/account/api/oauth/authorize

OAuth 2.1 authorization endpoint that initiates the authorization code flow. This endpoint supports both OAuth 2.1 and OpenID Connect protocols.

Method:

GET

Query Parameters:

• response_type (string, required): Must be code for authorization code flow.
• client_id (string, required): The client identifier registered with the authorization server.
• redirect_uri (string, required): The client's redirection endpoint URI. Must be a valid URL, and must match one of the redirect URIs registered for the client in exact string match.
• code_challenge (string, required): Code challenge for PKCE (Proof Key for Code Exchange). this value must be the Base64URL-encoded SHA256 hash of the code verifier. code verifier is a high-entropy cryptographic random string generated by the client. code verifier should saved securely for /account/api/oauth/token endpoint usage later.
• code_challenge_method (string, required): Code challenge method for PKCE. Must be S256.
• scope (string, optional): Space-delimited scope values. Include openid for OpenID Connect flows.
• response_mode (string, optional): Specifies how the result of the authorization request is formatted. should be query, fragment, form_post or web_message. default is query.
• state (string, optional): A string used to maintain state between the request and callback. you can store anything such as session identifier here.

OpenID Connect Parameters:

• nonce (string, optional): A string value used to associate a client session with an ID token, and to mitigate replay attacks. Since PKCE is already used for authorization code flow security, we do not recommend using nonce unless you are using ID tokens for specific purposes.
• display (string, optional): ASCII string value that specifies how the authorization server displays authentication pages to the end-user.
• prompt (string, optional): Space-delimited list of ASCII string values. If set to none, no user interaction is allowed.
• max_age (string, optional): Maximum authentication age in seconds.
• ui_locales (string, optional): End-user's preferred languages for the user interface.
• id_token_hint (string, optional): ID token previously issued by the authorization server.
• login_hint (string, optional): Hint to the authorization server about the login identifier the end-user might use to log in.
• acr_values (string, optional): Requested authentication context class reference values.

Responses:

Success (302 Redirect):

Redirects to the redirect_uri with an authorization code:

https://client.example.com/callback?code=AUTHORIZATION_CODE&state=STATE_VALUE

Error Responses (302 Redirect):

• invalid_request: Invalid redirect_uri or consent token
• access_denied: User denied the authorization request
• unsupported_response_type: Only response_type=code is supported
• interaction_required: User interaction is required (when prompt=none)

Example Request:

GET /account/api/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fclient.example.com%2Fcallback&scope=openid&state=xyz&nonce=n-0S6_WzA2Mj

/account/api/oauth/token

OAuth 2.1 token endpoint that exchanges authorization codes for access tokens. This endpoint supports both OAuth 2.1 and OpenID Connect protocols with PKCE (Proof Key for Code Exchange) support.

Method:

POST

Authentication:

This endpoint supports multiple client authentication methods:

• HTTP Basic Authentication: Send client_id and client_secret in Authorization header
• Client Secret in Body: Include client_secret in request body
• Public Clients: No authentication required for clients registered with token_endpoint_auth_method=none

Content Types:

This endpoint accepts the following content types:

• application/json
• application/x-www-form-urlencoded
• multipart/form-data

Content-Type header must be set accordingly based on the request body format. if the header is missing, content type will be assumed according to OAuth 2.1 specification.

Request Parameters (authorization_code grant type):

• grant_type (string, required): Must be authorization_code
• code (string, required): The authorization code received from the authorization endpoint
• redirect_uri (string, required): The same redirect URI used in the authorization request
• client_id (string, required): The client identifier (can be in Authorization header or body)
• client_secret (string, required): Required unless client uses token_endpoint_auth_method=none
• code_verifier (string, required): Code verifier for PKCE validation, used on /account/api/oauth/authorize endpoint code_challenge

Request Parameters (refresh_token grant type):

• grant_type (string, required): Must be refresh_token
• refresh_token (string, required): The refresh token received from a previous token response
• client_id (string, required): The client identifier (can be in Authorization header or body)
• client_secret (string, required): Required unless client uses token_endpoint_auth_method=none

Success Response (200 OK):

OAuth 2.1 Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "risuai"
}

OpenID Connect Response (with openid scope):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer", 
  "expires_in": 600,
  "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "openid risuai"
}

Response Fields:

• access_token: access token for accessing protected resources
• token_type: Always "Bearer"
• expires_in: Token lifetime in seconds
• id_token: JWT ID token (only if openid scope was requested)
• scope: Granted scopes
• refresh_token: Refresh token for obtaining new access tokens (If has refresh_token scope when authorization_code grant type, or always when refresh_token grant type for refresh token rotation)

ID Token Claims (OpenID Connect):

When the openid scope is included, the ID token contains:

• iss: Issuer (https://account.sionyw.com)
• sub: Subject (user ID)
• aud: Audience (client_id)
• exp: Expiration time
• iat: Issued at time
• auth_time: Time when user authentication occurred
• nonce: The nonce value from the authorization request, if provided

Error Responses (400 Bad Request):

• invalid_request: Missing required parameters (code, client_id, redirect_uri, code_verifier for PKCE)
• unsupported_grant_type: Only authorization_code grant type is supported
• invalid_grant: Invalid authorization code, client_id, or code_verifier
• invalid_client: Invalid client_secret or client authentication failed
• invalid_scope: Client not authorized for requested scope

Example Requests:

Basic Authentication (JSON):

POST /account/api/oauth/token
Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "redirect_uri": "https://client.example.com/callback"
}

Client Secret in Body (Form):

POST /account/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=CODE&redirect_uri=https://client.example.com/callback&client_id=CLIENT_ID&client_secret=CLIENT_SECRET

PKCE Request:

POST /account/api/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "redirect_uri": "https://client.example.com/callback",
  "client_id": "CLIENT_ID",
  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
}

CORS Headers:

This endpoint includes CORS headers to allow cross-origin requests:

• Access-Control-Allow-Origin: *
• Access-Control-Allow-Methods: POST, OPTIONS
• Access-Control-Allow-Headers: Content-Type, Authorization

/account/api/oauth/register

Register a new OAuth client application. follows OAuth 2.0 standard for client registration and OpenID Connect Dynamic Client Registration 1.0.

Method:

POST

Request Body:

• redirect_uris (array of strings, required): List of allowed redirect URIs for the client application. Each URI must be a valid URL.
• token_endpoint_auth_method (string, optional): Authentication method for the token endpoint. Must be one of: client_secret_basic, client_secret_post, none. Default is client_secret_basic.
• grant_types (array of strings, optional): Grant types the client will use. Must include values from: authorization_code, refresh_token. Default is ["authorization_code"]
• response_types (array of strings, optional): Response types the client will use. Must include values from: code, token, id_token. Default is ["code"].
• client_name (string, optional): Human-readable name of the client application. Must be less than 100 characters.
• client_uri (string, optional): URL of the client application's home page. Must be less than 200 characters.
• software_id (string, optional): Identifier for the client software. Must be less than 100 characters.
• software_version (string, optional): Version of the client software. Must be less than 50 characters.
• scope (string, optional): Space-separated list of scopes.
• logo_uri (string, optional): URL that references a logo for the client application. Must be less than 200 characters.
• tos_uri (string, optional): URL that points to a human-readable terms of service document. Must be less than 200 characters.
• policy_uri (string, optional): URL that points to a human-readable privacy policy document. Must be less than 200 characters.

Content Types:

This endpoint accepts the following content types:

• application/json
• application/x-www-form-urlencoded
• multipart/form-data

if the header is missing, content type will be assumed according to its specification.

Response (201 Created):

{
  "client_id": "generated_client_id",
  "client_secret": "generated_client_secret",
  "client_id_issued_at": 1234567890,
  "client_secret_expires_at": 0,
  // Other client metadata fields...
}

Note: If token_endpoint_auth_method is set to none, It will be treated as a public client, which means no client_secret will be issued, and some restrictions will apply.

Error Responses (400 Bad Request):

• invalid_client_metadata: Invalid or missing required parameters
• unapproved_software_statement: Unsupported grant types or response types

Example Request:

{
  "redirect_uris": ["https://example.com/callback"],
  "client_name": "My OAuth App",
  "client_uri": "https://example.com",
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "scope": "openid"
}

CORS Headers:

This endpoint does not include CORS headers, as it is intended for server-to-server communication.

/account/api/oauth/userinfo

OpenID Connect UserInfo endpoint that returns user profile information. This endpoint requires a valid access token with the openid scope.

Methods:

GET, POST

Authentication:

This endpoint requires a valid access token obtained from the token endpoint. The access token must include the openid scope.

• Authorization Header: Authorization: Bearer ACCESS_TOKEN

Request Parameters:

No additional parameters are required. The user information is determined from the provided access token.

Success Response (200 OK):

{
  "sub": "user_id_string",
  "nickname": "username", 
  "preferred_username": "username"
}

Response Fields:

• sub: Subject identifier (user ID) - unique identifier for the user
• nickname: User's display name/username
• preferred_username: User's preferred username (same as nickname)

Error Responses (401 Unauthorized):

Returns 401 with WWW-Authenticate header when:

• Access token is missing, invalid, or expired
• Access token doesn't include the required openid scope
• User account associated with the token cannot be found

Error Response Format:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Userinfo", error="invalid_token", error_description="The access token is invalid or has expired"
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

Unauthorized

Example Requests:

GET Request:

GET /account/api/oauth/userinfo
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

POST Request:

POST /account/api/oauth/userinfo
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

CORS Headers:

This endpoint includes CORS headers to allow cross-origin requests:

• Access-Control-Allow-Origin: *
• Access-Control-Allow-Methods: GET, POST, OPTIONS
• Access-Control-Allow-Headers: Content-Type, Authorization

OpenID Connect Compliance:

This endpoint follows the OpenID Connect UserInfo specification and returns standard claims. The response format is compliant with OpenID Connect Core 1.0 UserInfo.