Authentication (OAuth)

OAuth Flow

Gency follows the OAuth 2.0 standard and provides a secure authorization flow in which users grant permissions to an app.

Authorization Code Flow

This is the most recommended method, and it proceeds in three steps.

Authorization Request

Redirect the user to the Gency authorization page.

GET https://openapi.gency.ai/oauth/authorize
  ?response_type=code
  &client_id={client_id}
  &redirect_uri={redirect_uri}
  &scope=product:read product:write
  &state={random_state}

• response_type: code (required)
• client_id: The Client ID issued in the API Center (required)
• redirect_uri: The Redirect URI registered in the API Center (required)
• scope: The permissions to request (space-separated; if omitted, all scopes registered for the app are used)
• state: A random string for CSRF protection (recommended)

When Gency receives this request, it generates an authorize_key and redirects the user to the Gency OAuth login/consent page (https://gency.ai/oauth/authorize?authorize_key=...).

User Login and Consent

The user logs in with their email/password on the Gency OAuth page. After logging in, they review information such as the app name and requested scopes, and give their consent.

Receiving the Authorization Code and Exchanging for a Token

Once the user consents, Gency delivers the authorization code to the registered redirect_uri.

{redirect_uri}?code={authorization_code}&state={state}

Use this code to request an Access Token.

POST https://openapi.gency.ai/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={authorization_code}
&redirect_uri={redirect_uri}
&client_id={client_id}
&client_secret={client_secret}

Response on success:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOi...",
  "scope": "product:read product:write"
}

Token Refresh

When the Access Token expires, you can refresh it with the Refresh Token.

POST https://openapi.gency.ai/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token={refresh_token}
&client_id={client_id}
&client_secret={client_secret}

Token Introspection

Check the validity of an issued token.

POST https://openapi.gency.ai/oauth/introspect
Content-Type: application/x-www-form-urlencoded

token={access_token}
&client_id={client_id}
&client_secret={client_secret}

Token Revocation

Invalidate a token that is no longer used.

POST https://openapi.gency.ai/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token={token}
&client_id={client_id}
&client_secret={client_secret}

Token Information Summary

Item	Value
Access Token lifetime	1 hour (3,600 seconds)
Refresh Token lifetime	90 days (7,776,000 seconds)
Authorization Code lifetime	10 minutes (600 seconds)
Token Type	Bearer
Issuer	https://openapi.gency.ai

Server Metadata

OAuth2 server configuration information can be found at the endpoint below.

GET https://openapi.gency.ai/.well-known/oauth-authorization-server

---