Applications

Applications in AuthStack represent OAuth clients that can authenticate users through your AuthStack organization. Each application has its own credentials, redirect URIs, and webhook configurations.

Overview

Applications are the core building blocks of your authentication setup:

• Client credentials - Each app has a unique Client ID and Secret
• OAuth providers - Configure which social logins are available
• Webhooks - Receive real-time notifications for user events
• Usage tracking - Monitor authentication requests per application
• Custom branding - Personalize the OAuth login page with your app’s colors and logo

Endpoints

Method	Endpoint	Description
GET	/api/applications	List all applications
GET	/api/applications/{appId}	Get application details
POST	/api/applications	Create a new application
PUT	/api/applications/{appId}	Update an application
DELETE	/api/applications/{appId}	Delete an application
POST	/api/applications/{appId}/regenerate-secret	Regenerate client secret

Webhook Endpoints

See Webhooks API for detailed webhook documentation.

Method	Endpoint	Description
GET	/api/applications/{appId}/webhooks	List webhooks
POST	/api/applications/{appId}/webhooks	Create webhook
PUT	/api/applications/{appId}/webhooks/{webhookId}	Update webhook
DELETE	/api/applications/{appId}/webhooks/{webhookId}	Delete webhook

Provider Endpoints

Method	Endpoint	Description
GET	/api/applications/{appId}/providers	List enabled providers
POST	/api/applications/{appId}/providers	Enable a provider
DELETE	/api/applications/{appId}/providers/{providerId}	Disable a provider

Creating an Application

POST /api/applications
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "My Mobile App",
  "description": "iOS and Android mobile application",
  "logoUrl": "https://myapp.com/logo.png",
  "primaryColor": "#3B82F6",
  "secondaryColor": "#10B981",
  "redirectUris": [
    "myapp://callback",
    "https://myapp.com/auth/callback"
  ]
}

Request Body

Field	Type	Required	Description
name	string	Yes	Application name displayed to users
description	string	No	Brief description of your application
logoUrl	string	No	URL to your app’s logo (displayed on OAuth page)
primaryColor	string	No	Hex color for primary UI elements (e.g., #3B82F6)
secondaryColor	string	No	Hex color for secondary UI elements
redirectUris	string[]	No	Allowed OAuth callback URLs
allowedScopes	string[]	No	OAuth scopes this app can request

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Mobile App",
  "description": "iOS and Android mobile application",
  "clientId": "1OXlgFq035ixdKA8A3tMDqiIF-IMkgEO",
  "clientSecret": "cs_abc123...",
  "logoUrl": "https://myapp.com/logo.png",
  "primaryColor": "#3B82F6",
  "secondaryColor": "#10B981",
  "redirectUris": [
    "myapp://callback",
    "https://myapp.com/auth/callback"
  ],
  "isActive": true,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": null
}

Caution

The clientSecret is only returned once when creating the application. Store it securely.

Getting Application Details

GET /api/applications/{appId}
Authorization: Bearer <access_token>

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Mobile App",
  "description": "iOS and Android mobile application",
  "clientId": "1OXlgFq035ixdKA8A3tMDqiIF-IMkgEO",
  "logoUrl": "https://myapp.com/logo.png",
  "primaryColor": "#3B82F6",
  "secondaryColor": "#10B981",
  "redirectUris": [
    "myapp://callback",
    "https://myapp.com/auth/callback"
  ],
  "isActive": true,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-16T14:22:00Z",
  "providers": [
    {
      "id": "provider-id",
      "type": "google",
      "isEnabled": true
    }
  ]
}

Updating an Application

PUT /api/applications/{appId}
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "My Updated App",
  "description": "Updated description",
  "logoUrl": "https://myapp.com/new-logo.png",
  "primaryColor": "#6366F1",
  "secondaryColor": "#22C55E",
  "redirectUris": [
    "myapp://callback",
    "https://myapp.com/auth/callback",
    "https://staging.myapp.com/auth/callback"
  ],
  "isActive": true
}

Tip

Set primaryColor and secondaryColor to null to remove custom branding and use the default AuthStack theme.

Regenerating Client Secret

If your client secret is compromised, regenerate it:

POST /api/applications/{appId}/regenerate-secret
Authorization: Bearer <access_token>

Response

{
  "clientSecret": "cs_newSecret456..."
}

Caution

After regenerating, update all instances of your application to use the new secret. The old secret will immediately stop working.

Deleting an Application

DELETE /api/applications/{appId}
Authorization: Bearer <access_token>

Danger

Deleting an application will:

• Revoke all access tokens issued by this application
• Delete all webhook configurations
• Remove all provider configurations
• This action cannot be undone

OAuth Providers

Configure which OAuth providers are available for each application.

Enable a Provider

POST /api/applications/{appId}/providers
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "type": "google",
  "clientId": "your-google-client-id",
  "clientSecret": "your-google-client-secret"
}

Supported Providers

Provider	Type Value	Status
Google	google	Available
GitHub	github	Available
Microsoft	microsoft	Available
Apple	apple	Available
Discord	discord	Available

Webhooks

Each application can have multiple webhooks to receive real-time notifications. See the Webhooks API documentation for:

• Creating and managing webhooks
• Verifying webhook signatures
• Handling webhook events
• Retry behavior and best practices

OAuth 2.0 Authorization Code Flow

Applications use the OAuth 2.0 Authorization Code flow with PKCE to authenticate users. See the OAuth 2.0 Authorization documentation for complete details.

Quick Overview

1. Redirect users to /oauth/authorize with your client_id and redirect_uri
2. Users see a login page with email/password and social login options
3. After login, users are redirected to your redirect_uri with an authorization code
4. Exchange the code for tokens at /oauth/token

GET /oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=openid profile email&
  code_challenge=PKCE_CHALLENGE&
  code_challenge_method=S256

Tip

Always use PKCE for enhanced security, especially for public clients like mobile apps and SPAs.

Client Credentials Flow

For server-to-server authentication, use client credentials:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

Custom Branding

Personalize the OAuth authorization page with your application’s branding to provide a seamless authentication experience for your users.

Branding Options

Field	Description	Example
logoUrl	URL to your application’s logo (recommended: 128x128px PNG)	https://myapp.com/logo.png
primaryColor	Hex color for buttons and primary UI elements	#3B82F6
secondaryColor	Hex color for secondary accents	#10B981

How Branding is Applied

When users are redirected to the AuthStack OAuth authorization page, your custom branding is displayed:

• Logo - Shown at the top of the login form (falls back to app initial if not set)
• Primary Color - Applied to the “Sign In” button and checkmarks
• Secondary Color - Used for secondary UI accents

Example

{
  "logoUrl": "https://myapp.com/logo.png",
  "primaryColor": "#6366F1",
  "secondaryColor": "#22C55E"
}

Tip

Use colors that match your application’s brand identity for a cohesive user experience. Test with both light and dark backgrounds to ensure good contrast.

Best Practices

1. Separate environments - Create different applications for development, staging, and production
2. Limit redirect URIs - Only include necessary callback URLs
3. Rotate secrets - Periodically regenerate client secrets
4. Monitor usage - Review authentication metrics in the dashboard
5. Configure webhooks - Set up webhooks to react to user events in real-time
6. Use custom branding - Add your logo and colors for a seamless authentication experience

Error Handling

Status Code	Description
400	Invalid request (missing name, invalid redirect URI)
401	Unauthorized - invalid or expired token
403	Forbidden - not authorized for this organization
404	Application not found
409	Conflict - application name already exists
500	Server error