Skip to main content

​
Overview

The authorization URL endpoint initiates the OAuth 2.0 authorization flow for Single Sign-On (SSO). This endpoint redirects users to their configured Identity Provider (IdP) for authentication.

​
Endpoint

​
method
string
default:"GET"
GET
​
url
string
{SCALEKIT_ENVIRONMENT_URL}/oauth/authorize

​
Query Parameters

​
client_id
string
required
Your Scalekit application client ID. Obtain this from the Scalekit Dashboard under API Config.
​
redirect_uri
string
required
The URL where users will be redirected after authentication. Must match one of the redirect URIs configured in your Scalekit application settings.
​
response_type
string
required
OAuth response type. Use code for authorization code flow.
​
scope
string
required
Space-separated list of OAuth scopes. Common scopes: openid, email, profile.
​
organization_id
string
Unique identifier of the organization. Use this to initiate SSO for a specific organization. Either organization_id or connection_id must be provided.
​
connection_id
string
Unique identifier of the SSO connection. Use this to initiate SSO with a specific connection. Either organization_id or connection_id must be provided.
​
state
string
Optional state parameter for CSRF protection. The value will be returned in the callback.
​
nonce
string
Optional nonce value for replay attack protection in OpenID Connect flows.

​
Request Examples

    ​
    Response

    The endpoint performs a 302 redirect to the configured Identity Provider’s login page. After successful authentication, the IdP redirects back to your redirect_uri with an authorization code.

    ​
    Callback Parameters

    Your redirect URI will receive the following query parameters:
    ​
    code
    string
    required
    Authorization code to exchange for tokens. This code is single-use and expires after a short period (typically 10 minutes).
    ​
    state
    string
    The state parameter you provided in the authorization request. Use this to prevent CSRF attacks.

    ​
    Callback Example

    https://yourapp.com/auth/callback?code=auth_code_123456&state=random_state_value

    ​
    Error Responses

    ​
    error
    string
    Error code indicating what went wrong.
    ​
    error_description
    string
    Human-readable description of the error.

    ​
    Common Errors

    Error CodeDescriptionSolution
    invalid_requestMissing or invalid required parametersVerify all required parameters are included
    unauthorized_clientInvalid client_idCheck your client_id in Scalekit Dashboard
    invalid_redirect_uriRedirect URI not configuredAdd the redirect_uri to your application settings
    invalid_scopeRequested scope is invalidUse valid OAuth scopes (openid, email, profile)
    organization_not_foundOrganization ID does not existVerify the organization_id is correct
    connection_not_foundConnection ID does not existVerify the connection_id is correct

    ​
    Security Considerations

    Critical Security Practices:
    1. State Parameter: Always include a unique state parameter to prevent CSRF attacks. Verify the state value when handling the callback.
    2. Redirect URI Validation: Only use redirect URIs that are pre-configured in your Scalekit application. Never accept user-provided redirect URIs.
    3. HTTPS Only: Always use HTTPS for redirect URIs in production. HTTP redirect URIs are insecure and may be rejected.
    4. Code Expiration: Authorization codes expire quickly (typically 10 minutes). Exchange them for tokens immediately.
    5. Single Use: Authorization codes are single-use only. Do not reuse codes.

    ​
    Implementation Flow

    1. Generate Authorization URL: Create the authorization URL with appropriate parameters
    2. Redirect User: Redirect the user’s browser to the authorization URL
    3. User Authenticates: User logs in through their Identity Provider
    4. Receive Callback: Handle the callback with the authorization code
    5. Exchange Code: Use the Token Exchange endpoint to get user tokens

    ​
    Next Steps

    Token Exchange

    Exchange authorization codes for access tokens

    Session Management

    Validate and manage user sessions

    Build docs developers (and LLMs) love

    Get started for freeTalk to us