API reference

Request formats, response shapes, OAuth examples, and troubleshooting for tenant integrations with SoWayJuli.

Response format

JSON endpoints return an envelope. Always check the HTTP status first, then inspect success and error.code.

{
	"success": true,
	"data": { "example": "value" },
	"error": null,
	"requestId": "request-correlation-id"
}

{
	"success": false,
	"data": null,
	"error": { "code": "INVALID_GRANT", "message": "invalid_grant" },
	"requestId": "request-correlation-id"
}

Website account APIs

• GET /api/v0/backend-api/PasswordEncryptionKey supports the website's password forms.
• POST /api/v0/backend-api/Register creates a SoWayJuli user account when registration is enabled.
• POST /api/v0/backend-api/Login establishes the website's browser session.
• GET /api/v0/backend-api/Me returns the current website account.
• POST /api/v0/backend-api/Logout ends the website's browser session.
• POST /api/v0/backend-api/UpdateProfile, POST /api/v0/backend-api/ChangeEmail, and POST /api/v0/backend-api/ChangePassword manage the signed-in website account.

OAuth authorization

POST /api/v0/backend-api/graph/authorize

Begins an authorization transaction. The tenant_id, client_id, software_id, and callback must match an active application registration. scope is a space-separated list and defaults to profile. Generate a random state per attempt and validate it at the callback. Use PKCE with S256.

curl -X POST "$BASE_URL/api/v0/backend-api/graph/authorize" \
	-H "Content-Type: application/json" \
	-H "Accept: application/json" \
	-d '{
		"tenant_id":"TENANT_ID",
		"client_id":"CLIENT_ID",
		"software_id":"SOFTWARE_ID",
		"callback":"http://localhost:8080/callback",
		"scope":"profile email",
		"state":"RANDOM_STATE",
		"code_challenge":"BASE64URL_SHA256_OF_VERIFIER",
		"code_challenge_method":"S256"
	}'

On HTTP success, inspect data.transaction_status. A pending transaction returns a data.login_url; open it in the user's browser. A response can be HTTP 200 while the transaction status is Failed, so do not treat HTTP 200 alone as authorization success.

POST /api/v0/backend-api/token

Exchange an authorization code. Codes expire quickly and can only be used once. The callback and client ID must match the authorization request.

curl -X POST "$BASE_URL/api/v0/backend-api/token" \
	-H "Content-Type: application/json" \
	-d '{
		"grant_type":"authorization_code",
		"code":"CALLBACK_CODE",
		"callback":"http://localhost:8080/callback",
		"client_id":"CLIENT_ID",
		"code_verifier":"ORIGINAL_PKCE_VERIFIER"
	}'

The response data contains access_token, token_type (Bearer), expires_in in seconds, refresh_token, and granted scope.

Refresh a token

curl -X POST "$BASE_URL/api/v0/backend-api/token" \
	-H "Content-Type: application/json" \
	-d '{"grant_type":"refresh_token","client_id":"CLIENT_ID","refresh_token":"CURRENT_REFRESH_TOKEN"}'

Refresh tokens rotate: store the newly returned refresh token and discard the old one. Reusing the old token returns invalid_grant.

Profile and media

GET /user/profile

Requires an access token in the Authorization header. The profile scope grants identity/profile fields, email grants the email field, and phone grants the phone number.

curl "$BASE_URL/user/profile" \
	-H "Authorization: Bearer ACCESS_TOKEN" \
	-H "Accept: application/json"

Fields outside the granted scopes contain NOT ALLOWED CURRENT SCOPE; this is a scope result, not a missing database value.

• GET /usercdn/user/profile/avatar and GET /usercdn/user/profile/banner return image bytes and require a bearer token with profile.
• POST /api/v0/backend-api/UploadAvatar and POST /api/v0/backend-api/UploadBanner accept one multipart image file, require profile, and reject files at or above 64 MiB.

POST /user/logout

Tenant integrations may use this endpoint to revoke the bearer access token presented in the request. It does not sign out the user's SoWayJuli browser session or revoke other tokens.

curl -X POST "$BASE_URL/user/logout" \
	-H "Authorization: Bearer ACCESS_TOKEN" \
	-H "Accept: application/json"

A successful response returns data.logged_out: true and data.token_revoked: true. Missing, invalid, expired, or already revoked tokens return 401 Unauthorized.

Troubleshooting

Open the troubleshooting guide →