Skip to main content

Integration from Any Language

SyAuth is a standard OAuth 2.0 / OpenID Connect provider. You can integrate it from any programming language that can make HTTP requests.

Building a Backend Service? If you are building a daemon, CLI, or service that engages with SyAuth directly (without a human user present), check out the Machine-to-Machine Guide.

Prerequisites​

  • A SyAuth Application created in the Dashboard
  • Your client_id and redirect_uri
  • Basic understanding of OAuth 2.0

OAuth 2.0 Flow Overview​

1. Generate PKCE code_verifier and code_challenge
2. Redirect user to /oauth/authorize
3. User logs in and authorizes
4. SyAuth redirects back with authorization code
5. Exchange code for tokens at /oauth/token
6. Use access_token to call APIs
7. Refresh token when expired

Step 1: Generate PKCE Parameters​

PKCE (Proof Key for Code Exchange) is required for security.

Generate code_verifier​

Create a random 43-128 character string using URL-safe characters:

import secrets
import base64

code_verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).decode('utf-8').rstrip('=')

Generate code_challenge​

SHA256 hash of code_verifier, then base64url encode:

import hashlib

code_challenge = base64.urlsafe_b64encode(
    hashlib.sha256(code_verifier.encode('utf-8')).digest()
).decode('utf-8').rstrip('=')

Step 2: Redirect to Authorization Endpoint​

Build the authorization URL and redirect the user:

https://api.syauth.com/e/v1/oauth/authorize?
  response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=openid profile email
  &state=RANDOM_STATE_STRING
  &code_challenge=CODE_CHALLENGE_HERE
  &code_challenge_method=S256

Parameters:

  • response_type: Always code
  • client_id: Your application's client ID
  • redirect_uri: Must match exactly what's configured in Dashboard
  • scope: Space-separated scopes (e.g., openid profile email)
  • state: Random string to prevent CSRF (verify this matches on callback)
  • code_challenge: Generated in Step 1
  • code_challenge_method: Always S256

Step 3: Handle the Callback​

After the user logs in, SyAuth redirects to your redirect_uri with:

https://your-app.com/callback?
  code=AUTHORIZATION_CODE
  &state=SAME_STATE_YOU_SENT
  1. Verify state matches what you sent
  2. Extract the code parameter
  3. Exchange it for tokens (Step 4)

Step 4: Exchange Code for Tokens​

Make a POST request to the token endpoint:

curl -X POST https://api.syauth.com/e/v1/oauth/token/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "redirect_uri=YOUR_REDIRECT_URI" \
  -d "code_verifier=CODE_VERIFIER_FROM_STEP1"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Step 5: Use Access Token​

Include the access token (from the Step 4 response) in API requests:

# Replace ACCESS_TOKEN with the "access_token" value received in Step 4
curl https://api.syauth.com/e/v1/user/profile/ \
  -H "Authorization: Bearer ACCESS_TOKEN_HERE"

Step 6: Refresh Token​

When the access token expires (after 1 hour), use the refresh token:

curl -X POST https://api.syauth.com/e/v1/oauth/token/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=REFRESH_TOKEN_HERE" \
  -d "client_id=YOUR_CLIENT_ID"

Complete Example: Python​

import requests
import secrets
import hashlib
import base64
from urllib.parse import urlencode

# Step 1: Generate PKCE
code_verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).decode('utf-8').rstrip('=')
code_challenge = base64.urlsafe_b64encode(
    hashlib.sha256(code_verifier.encode('utf-8')).digest()
).decode('utf-8').rstrip('=')

# Step 2: Build authorization URL
auth_params = {
    'response_type': 'code',
    'client_id': 'YOUR_CLIENT_ID',
    'redirect_uri': 'http://localhost:3000/callback',
    'scope': 'openid profile email',
    'state': secrets.token_urlsafe(32),
    'code_challenge': code_challenge,
    'code_challenge_method': 'S256'
}
auth_url = f"https://api.syauth.com/e/v1/oauth/authorize?{urlencode(auth_params)}"
print(f"Visit: {auth_url}")

# Step 3: User logs in and you get the code
authorization_code = input("Enter authorization code: ")

# Step 4: Exchange for tokens
token_response = requests.post('https://api.syauth.com/e/v1/oauth/token/', data={
    'grant_type': 'authorization_code',
    'code': authorization_code,
    'client_id': 'YOUR_CLIENT_ID',
    'redirect_uri': 'http://localhost:3000/callback',
    'code_verifier': code_verifier
})

tokens = token_response.json()
access_token = tokens['access_token']

# Step 5: Use access token
user_response = requests.get(
    'https://api.syauth.com/e/v1/user/profile/',
    headers={'Authorization': f'Bearer {access_token}'}
)

print(user_response.json())

Next Steps​

Need Help?​

  • Check the the OAuth 2.0 endpoints for detailed endpoint documentation
  • For convenience, use our SDKs (Next.js, Django)