Social App Management API Documentation

Overview

The Social App Management API allows you to programmatically create and manage OAuth social applications (providers) for your multi-tenant Django application. This API provides simple CRUD operations with tenant isolation and automatic configuration.

Base URL: /api/auth/social-apps/

Authentication:

• List: No authentication required (public endpoint for login pages)
• All other endpoints: JWT Bearer Token required

Permissions:

• List: Public (no authentication required)
• Retrieve: Any authenticated user
• Create/Update/Delete: Superusers or Organization owners only

---

Table of Contents

1. List Social Apps
2. Create Social App
3. Get Social App Details
4. Update Social App
5. Delete Social App
6. Common Providers Examples
7. Error Codes

---

1. List Social Apps

Get a list of all social apps for the current tenant. This endpoint is public (no authentication required) to allow login pages to fetch available OAuth providers.

Endpoint: GET /api/auth/social-apps/

Authentication: Not required (public endpoint)

Query Parameters:

Parameter	Type	Description
search	string	Search by name, provider, client_id, or provider_id
provider	string	Filter by provider (e.g., google, github, openid_connect)
ordering	string	Order by field (e.g., name, -name, provider)
page	integer	Page number for pagination (default: 1)
page_size	integer	Number of results per page (default: 10, max: 100)

Example Request (No Authentication Required):

# Public access - no token needed
curl -X GET "http://localhost:8000/api/auth/social-apps/"

Example Request with Filters:

curl -X GET "http://localhost:8000/api/auth/social-apps/?provider=openid_connect"

Response (200 OK):

{
  "success": true,
  "message": "Social apps retrieved successfully",
  "data": [
    {
      "id": 1,
      "provider": "openid_connect",
      "provider_id": "keycloak",
      "name": "Keycloak SSO",
      "provider_display": "OpenID Connect",
      "is_configured": true,
      "icon": "https://cdn.example.com/keycloak-icon.svg",
      "auto_redirect": false
    },
    {
      "id": 2,
      "provider": "google",
      "provider_id": "",
      "name": "Google OAuth",
      "provider_display": "Google",
      "is_configured": true,
      "icon": "mdi-google",
      "auto_redirect": true
    }
  ],
  "total": 2,
  "page": 1,
  "page_size": 10,
  "total_pages": 1
}

Custom Parameters (Flattened in List):

• icon (string): Icon URL or identifier for the provider button
• auto_redirect (boolean): Whether to auto-redirect to this provider on login page

Use Case - Login Page:

// Fetch providers without authentication
fetch('http://localhost:8000/api/auth/social-apps/')
  .then(res => res.json())
  .then(response => {
    if (response.success) {
      response.data.forEach(provider => {
        if (provider.is_configured) {
          // Create OAuth button with icon
          createProviderButton({
            name: provider.name,
            icon: provider.icon,
            provider: provider.provider,
            autoRedirect: provider.auto_redirect
          });
        }
      });
    }
  });

---

2. Create Social App

Create a new OAuth social application.

Endpoint: POST /api/auth/social-apps/

Authentication: Required (Superuser or Organization Owner)

Request Body:

Field	Type	Required	Description
provider	string	Yes	OAuth provider type (e.g., google, github, openid_connect)
provider_id	string	Conditional	Required for OpenID Connect and SAML providers
name	string	Yes	Display name for this OAuth configuration
client_id	string	Yes	OAuth client ID from provider console
secret	string	Yes	OAuth client secret (will be masked in responses)
key	string	No	Additional key field (rarely used)
settings	object	Conditional	Provider-specific settings (required for OpenID Connect). Can include icon and auto_redirect custom parameters.

Custom Parameters in settings:

• icon (string, optional): Icon URL or identifier for the provider button (e.g., "https://cdn.example.com/icon.svg" or "mdi-google")
• auto_redirect (boolean, optional): Auto-redirect to this provider on login page (default: false)
• server_url (string, required for OpenID Connect): OIDC discovery URL

Example 1: Create OpenID Connect (Keycloak) with Custom Parameters

Request:

curl -X POST "http://localhost:8000/api/auth/social-apps/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openid_connect",
    "provider_id": "keycloak",
    "name": "Keycloak SSO",
    "client_id": "taruvi",
    "secret": "6GUvx3aEaFDhfreWTJm78Hwsip9LB3uR",
    "settings": {
      "server_url": "https://keycloakstag.eoxvantage.com/realms/taruvi/.well-known/openid-configuration",
      "icon": "https://cdn.example.com/keycloak-icon.svg",
      "auto_redirect": false
    }
  }'

Response (201 Created):

{
  "success": true,
  "message": "Social app created successfully",
  "data": {
    "id": 1,
    "provider": "openid_connect",
    "provider_id": "keycloak",
    "name": "Keycloak SSO",
    "client_id": "taruvi",
    "secret": "6GUvx3aEaFDhfreWTJm78Hwsip9LB3uR",
    "key": "",
    "settings": {
      "server_url": "https://keycloakstag.eoxvantage.com/realms/taruvi/.well-known/openid-configuration",
      "icon": "https://cdn.example.com/keycloak-icon.svg",
      "auto_redirect": false
    },
    "provider_display": "OpenID Connect",
    "is_configured": true
  }
}

Example 2: Create Google OAuth

Request:

curl -X POST "http://tenant1.127.0.0.1.nip.io:8000/api/auth/social-apps/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "name": "Google OAuth",
    "client_id": "123456789.apps.googleusercontent.com",
    "secret": "GOCSPX-abc123xyz789"
  }'

Example 3: Create GitHub OAuth

Request:

curl -X POST "http://tenant1.127.0.0.1.nip.io:8000/api/auth/social-apps/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "github",
    "name": "GitHub OAuth",
    "client_id": "Iv1.a1b2c3d4e5f6g7h8",
    "secret": "1234567890abcdef1234567890abcdef12345678"
  }'

Validation Errors

Missing Required Field:

{
  "client_id": ["This field is required."]
}

Invalid Provider:

{
  "provider": ["Invalid provider 'invalid'. Available providers: google, github, openid_connect, ..."]
}

OpenID Connect Missing provider_id:

{
  "provider_id": ["provider_id is required for OpenID Connect provider"]
}

OpenID Connect Missing server_url:

{
  "settings": ["server_url is required in settings for OpenID Connect. Example: {\"server_url\": \"https://your-idp.com/realms/your-realm\"}"]
}

---

3. Get Social App Details

Retrieve details of a specific social app. Secrets are masked for security. Custom parameters (icon, auto_redirect) are kept nested inside settings in this endpoint.

Endpoint: GET /api/auth/social-apps/{id}/

Authentication: Required

Example Request:

curl -X GET "http://localhost:8000/api/auth/social-apps/1/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response (200 OK):

{
  "id": 1,
  "provider": "openid_connect",
  "provider_id": "keycloak",
  "name": "Keycloak SSO",
  "client_id": "taruvi",
  "secret": "***HIDDEN***",
  "key": "",
  "settings": {
    "server_url": "https://keycloakstag.eoxvantage.com/realms/taruvi/.well-known/openid-configuration",
    "icon": "https://cdn.example.com/keycloak-icon.svg",
    "auto_redirect": false
  },
  "provider_display": "OpenID Connect",
  "is_configured": true
}

Note:

• The secret field is always masked as ***HIDDEN*** in GET responses for security
• Custom parameters (icon, auto_redirect) remain nested inside settings (not flattened like in the list endpoint)

---

4. Update Social App

Partially update an existing social app configuration. Only send the fields you want to change.

Endpoint: PATCH /api/auth/social-apps/{id}/

Authentication: Required (Superuser or Organization Owner)

Request Body: Any fields from Create (all optional)

Note: PATCH allows partial updates - only include fields you want to change. Missing fields will retain their current values.

Example 1: Update Only Name

curl -X PATCH "http://tenant1.127.0.0.1.nip.io:8000/api/auth/social-apps/1/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Keycloak SSO (Updated)"
  }'

Example 2: Rotate Secret Only

curl -X PATCH "http://tenant1.127.0.0.1.nip.io:8000/api/auth/social-apps/1/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "secret": "NEW-SECRET-KEY-HERE"
  }'

Example 3: Update Multiple Fields

curl -X PATCH "http://localhost:8000/api/auth/social-apps/1/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Keycloak SSO (Production)",
    "settings": {
      "server_url": "https://keycloak-prod.company.com/realms/company/.well-known/openid-configuration"
    }
  }'

Example 4: Update Custom Parameters (icon, auto_redirect)

curl -X PATCH "http://localhost:8000/api/auth/social-apps/1/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "server_url": "https://keycloak.example.com/realms/company/.well-known/openid-configuration",
      "icon": "mdi-key",
      "auto_redirect": true
    }
  }'

Response (200 OK):

{
  "success": true,
  "message": "Social app updated successfully",
  "data": {
    "id": 1,
    "provider": "openid_connect",
    "provider_id": "keycloak",
    "name": "Keycloak SSO",
    "client_id": "taruvi",
    "secret": "***HIDDEN***",
    "key": "",
    "settings": {
      "server_url": "https://keycloak.example.com/realms/company/.well-known/openid-configuration",
      "icon": "mdi-key",
      "auto_redirect": true
    },
    "provider_display": "OpenID Connect",
    "is_configured": true
  }
}

Note:

• The secret is masked in PATCH responses
• Custom parameters are nested inside settings
• Only specified fields are updated; others retain current values

---

5. Delete Social App

Delete a social app. Protected if users are actively using it.

Endpoint: DELETE /api/auth/social-apps/{id}/

Authentication: Required (Superuser or Organization Owner)

Example Request:

curl -X DELETE "http://localhost:8000/api/auth/social-apps/1/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Success Response (200 OK):

{
  "success": true,
  "message": "Social app deleted successfully"
}

Error Response - Users Exist (400 Bad Request):

{
  "success": false,
  "message": "Cannot delete social app. 5 user(s) are currently using this provider.",
  "suggestion": "Consider disabling the app instead or migrate users to another provider first.",
  "active_users": 5
}

---

6. Common Providers Examples

Google OAuth 2.0

Prerequisites:

1. Go to Google Cloud Console
2. Create a project or select existing one
3. Enable Google+ API
4. Create OAuth 2.0 credentials
5. Add authorized redirect URIs: https://yourdomain.com/accounts/google/login/callback/

Create Request:

{
  "provider": "google",
  "name": "Google OAuth",
  "client_id": "123456789.apps.googleusercontent.com",
  "secret": "GOCSPX-your-client-secret"
}

---

GitHub OAuth

Prerequisites:

1. Go to GitHub Developer Settings
2. Create a new OAuth App
3. Set authorization callback URL: https://yourdomain.com/accounts/github/login/callback/

Create Request:

{
  "provider": "github",
  "name": "GitHub OAuth",
  "client_id": "Iv1.your-client-id",
  "secret": "your-client-secret-here"
}

---

Microsoft OAuth (Azure AD)

Prerequisites:

1. Go to Azure Portal
2. Navigate to Azure Active Directory > App registrations
3. Create a new registration
4. Add redirect URI: https://yourdomain.com/accounts/microsoft/login/callback/
5. Create a client secret

Create Request:

{
  "provider": "microsoft",
  "name": "Microsoft OAuth",
  "client_id": "your-application-id",
  "secret": "your-client-secret"
}

---

Keycloak (OpenID Connect)

Prerequisites:

1. Access your Keycloak admin console
2. Create a client in your realm
3. Set Valid Redirect URIs: https://yourdomain.com/accounts/keycloak-*/login/callback/
4. Note your realm URL

Create Request:

{
  "provider": "openid_connect",
  "provider_id": "keycloak",
  "name": "Keycloak SSO",
  "client_id": "your-client-id",
  "secret": "your-client-secret",
  "settings": {
    "server_url": "https://keycloak.company.com/realms/company/.well-known/openid-configuration"
  }
}

Note: The server_url should point to the .well-known/openid-configuration endpoint.

---

Okta (OpenID Connect)

Prerequisites:

1. Go to Okta Developer Console
2. Create a new application (Web App)
3. Add Sign-in redirect URI: https://yourdomain.com/accounts/okta/login/callback/

Create Request:

{
  "provider": "openid_connect",
  "provider_id": "okta",
  "name": "Okta SSO",
  "client_id": "your-client-id",
  "secret": "your-client-secret",
  "settings": {
    "server_url": "https://your-domain.okta.com/.well-known/openid-configuration"
  }
}

---

Auth0 (OpenID Connect)

Prerequisites:

1. Go to Auth0 Dashboard
2. Create a new application (Regular Web Application)
3. Add Allowed Callback URLs: https://yourdomain.com/accounts/auth0/login/callback/

Create Request:

{
  "provider": "openid_connect",
  "provider_id": "auth0",
  "name": "Auth0 SSO",
  "client_id": "your-client-id",
  "secret": "your-client-secret",
  "settings": {
    "server_url": "https://your-tenant.auth0.com/.well-known/openid-configuration"
  }
}

---

7. Error Codes

HTTP Code	Description
200	Success
201	Created successfully
400	Bad request - validation error or deletion blocked
401	Unauthorized - missing or invalid authentication
403	Forbidden - insufficient permissions
404	Not found - social app doesn't exist
500	Internal server error

Common Error Responses

Authentication Missing:

{
  "detail": "Authentication credentials were not provided."
}

Permission Denied:

{
  "detail": "You do not have permission to perform this action."
}

Not Found:

{
  "detail": "Not found."
}

---

8. Important Settings

Auto-Connect Existing Users

The platform is configured with SOCIALACCOUNT_AUTO_CONNECT = True, which means:

✅ When a user logs in via OAuth (e.g., Keycloak):

• If a user with the same email already exists in the system
• The OAuth account will be automatically connected to that existing user
• The user will not be duplicated
• The user logs in with their existing account

This prevents duplicate accounts when users already exist in the system before enabling social login.

---

9. Integration with Allauth

After creating a social app via API, users can authenticate using the standard allauth endpoints:

Login Page

Visit: http://yourdomain.com/accounts/login/

The configured social login buttons will automatically appear on this page.

Programmatic Social Login (Headless)

Step 1: Get authorization URL

GET /api/auth/{provider}/redirect/

Step 2: Redirect user to OAuth provider

Step 3: Handle callback and get tokens

POST /api/auth/{provider}/token/

---

10. Troubleshooting

Social app created but not showing on login page

Check:

1. Ensure you're accessing the correct tenant domain
2. Verify SOCIALACCOUNT_USE_SITES = False in settings
3. Check admin interface: http://yourdomain.com/admin/socialaccount/socialapp/
4. Restart the web container: docker-compose restart web

Authentication fails with "Invalid client"

Solution:

1. Verify client_id and secret are correct
2. Check redirect URIs match in provider console
3. For OpenID Connect, verify server_url is accessible

Users are being duplicated

Check:

1. Ensure SOCIALACCOUNT_AUTO_CONNECT = True in settings
2. Verify email addresses match between systems
3. Check that email is being provided by the OAuth provider

---

11. Quick Start Example

Complete workflow to set up Keycloak OAuth:

# 1. Get JWT token
TOKEN=$(curl -X POST "http://tenant1.127.0.0.1.nip.io:8000/api/auth/jwt/token/" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password"}' | jq -r '.access')

# 2. Create Keycloak social app
curl -X POST "http://tenant1.127.0.0.1.nip.io:8000/api/auth/social-apps/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openid_connect",
    "provider_id": "keycloak",
    "name": "Keycloak SSO",
    "client_id": "taruvi",
    "secret": "your-secret",
    "settings": {
      "server_url": "https://keycloak.example.com/realms/company/.well-known/openid-configuration"
    }
  }'

# 3. Verify it was created
curl -X GET "http://tenant1.127.0.0.1.nip.io:8000/api/auth/social-apps/" \
  -H "Authorization: Bearer $TOKEN"

# 4. Test login
# Visit: http://tenant1.127.0.0.1.nip.io:8000/accounts/login/
# You should see "Login with OpenID Connect" button

---

Support

For issues or questions:

• Check logs: docker logs taruvi_web
• Review admin interface: /admin/socialaccount/socialapp/
• API documentation: /api/docs/ (Swagger UI)
• ReDoc: /api/redoc/

---

Last Updated: January 2025 API Version: 1.0.0 Django Version: 5.2.6 Allauth Version: 65.13.0