Skip to main content

​
OAuth Authentication

The Shinzo Platform supports OAuth authentication via Google and GitHub. This allows users to sign in without creating a separate password.

​
Google OAuth

​
Step 1: Get Authorization URL

GET /auth/oauth/google
Query Parameters:
FieldTypeRequiredDescription
returnTostringNoURL to redirect after successful authentication
Example Request: 
curl -X GET "https://api.app.shinzo.ai/auth/oauth/google?returnTo=https://app.shinzo.ai/dashboard"
Response: 
{
  "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&scope=..."
}
Redirect the user to the returned URL to initiate Google OAuth.

​
Step 2: Handle Callback

POST /auth/oauth/google/callback
After the user authorizes with Google, they’re redirected back with an authorization code. Send this code to complete authentication: Request Body:
FieldTypeRequiredDescription
codestringYesAuthorization code from Google
statestringNoState parameter for CSRF protection
Response: 
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "uuid": "usr_abc123",
    "email": "[email protected]"
  },
  "isNewUser": false
}

​
GitHub OAuth

​
Step 1: Get Authorization URL

GET /auth/oauth/github
Query Parameters:
FieldTypeRequiredDescription
returnTostringNoURL to redirect after successful authentication
Example Request: 
curl -X GET "https://api.app.shinzo.ai/auth/oauth/github?returnTo=https://app.shinzo.ai/dashboard"
Response: 
{
  "url": "https://github.com/login/oauth/authorize?client_id=...&redirect_uri=...&scope=..."
}

​
Step 2: Handle Callback

POST /auth/oauth/github/callback
Request Body:
FieldTypeRequiredDescription
codestringYesAuthorization code from GitHub
statestringNoState parameter for CSRF protection
Response: 
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "uuid": "usr_abc123",
    "email": "[email protected]"
  },
  "isNewUser": true
}

​
Response Fields

FieldTypeDescription
tokenstringJWT token for authenticated requests
userobjectUser profile information
isNewUserbooleanWhether this is a new account created via OAuth

​
Status Codes

CodeDescription
200Authentication successful
400Invalid request (missing code, invalid state)
401OAuth authentication failed

​
Notes

  • OAuth users don’t need to verify their email separately
  • If a user with the same email already exists (registered via email/password), the accounts are linked
  • The isNewUser field indicates whether a new account was created or an existing one was used