Copy page

Security

Authentication Setup

🔐 Authentication Setup Guide

Overview

Tech231 Platform uses Zitadel as its identity provider, implementing OAuth 2.0 and OpenID Connect for secure authentication. This guide walks you through setting up authentication for both service accounts (API access) and user accounts (application access).

Authentication Endpoint

All authentication requests go through:

Code
https://auth.tech231apps.net

Authentication Types

Service Accounts

Best for: Server-to-server API integration, automated systems, backend services

• Uses OAuth2 Client Credentials flow
• No user interaction required
• Long-lived access tokens
• Ideal for programmatic API access

User Accounts

Best for: Web applications, mobile apps, interactive dashboards

• Uses OAuth2 Authorization Code flow
• Requires user login
• Supports refresh tokens
• Multi-factor authentication (MFA) support

Setting Up a Service Account

Prerequisites

Before you begin, ensure you have:

• An active Tech231 Platform organization account
• Admin or Owner role in your organization
• Access to Zitadel at https://auth.tech231apps.net

Step 1: Log Into Zitadel

1. Navigate to https://auth.tech231apps.net
2. Click "Sign In"
3. Enter your credentials
4. Complete two-factor authentication (if enabled)

Step 2: Access Your Organization

1. After logging in, click on your profile icon (top right)
2. Select your organization from the dropdown
3. You'll be redirected to your organization's home page

Step 3: Create a Service User

1. Click on "Users" in the left sidebar

2. Switch to the "Service Users" tab

3. Click "New" or "Create Service User"

4. Fill in the service user details:

   • Username: A descriptive name (e.g., production-api-service, sms-integration-bot)
   • Name: Human-readable display name
   • Description: Purpose of this service account

5. Important: Set the Access Token Type to JWT

   • This is required for the Tech231 Platform API
   • Without JWT tokens, API requests will fail

6. Click "Create"

Step 4: Generate Client Credentials

1. After creating the service user, click on it to view details

2. Navigate to the "Actions" or "Client Secret" section

3. Click "New" to generate a client secret

4. Important: Copy the following immediately (they won't be shown again):

   • Client ID: Your service account identifier (starts with @)
   • Client Secret: Your service account password

5. Store these credentials securely:

   Code
   # Example: Save to environment variables
   export ZITADEL_CLIENT_ID="123456789012345678@your-org"
   export ZITADEL_CLIENT_SECRET="your-secret-here"

Step 5: Verify API Access

1. Click on "Projects" in the left sidebar

2. Select "Granted Projects"

3. Verify you see the Tech231 APIs:

   • SMS API
   • USSD API (if applicable)
   • Any other services you need

4. If APIs are missing:

   • Contact support at support@tech231apps.net
   • Request access to the specific APIs you need
   • Include your organization name and use case

Step 6: Authorize the Service User

1. Go to "Projects" → "Granted Projects"
2. Click on the SMS project (or relevant API)
3. Navigate to "Authorizations"
4. Click "New Authorization"
5. Select your service user from the dropdown
6. Configure the authorization:
   • Roles: Select roles needed (e.g., SMS.Send, SMS.Read)
   • Scopes: Platform will automatically include required scopes
7. Click "Save"

Step 7: Test Your Credentials

Test authentication using curl:

Code
curl -X POST "https://auth.tech231apps.net/oauth/v2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${ZITADEL_CLIENT_ID}" \
  -d "client_secret=${ZITADEL_CLIENT_SECRET}" \
  -d "scope=openid email profile urn:zitadel:iam:org:project:id:321914919689650215:aud"

Expected Response:

Code
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid email profile urn:zitadel:iam:org:project:id:321914919689650215:aud"
}

Setting Up User Authentication

For applications that require user login (web apps, mobile apps), implement the OAuth2 Authorization Code flow.

Step 1: Register Your Application

1. In Zitadel, go to "Projects" → "Granted Projects"

2. Select the Tech231 platform project

3. Navigate to "Applications"

4. Click "New Application"

5. Choose "Web" or "Native" depending on your app type

6. Configure:

   • Name: Your application name
   • Authentication Method:
     • Code (Authorization Code flow - recommended)
     • PKCE (for mobile/SPA apps)
   • Redirect URIs: Your callback URLs (e.g., https://yourapp.com/auth/callback)
   • Post Logout Redirect URIs: Where users go after logout

7. Click "Create"

8. Copy your Client ID (and Client Secret if applicable)

Step 2: Implement Authorization Flow

Authorization Request

Redirect users to the authorization endpoint:

Code
https://auth.tech231apps.net/oauth/v2/authorize?
  client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/auth/callback
  &response_type=code
  &scope=openid email profile offline_access urn:zitadel:iam:org:project:id:321914919689650215:aud
  &state=RANDOM_STATE_VALUE

Parameters:

• client_id: Your application's client ID
• redirect_uri: Must match a registered redirect URI
• response_type: Always code for Authorization Code flow
• scope: Space-separated list of required scopes
• state: Random value to prevent CSRF attacks

Token Exchange

After user authorizes, they're redirected back with a code:

Code
https://yourapp.com/auth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE_VALUE

Exchange the code for tokens:

Code
curl -X POST "https://auth.tech231apps.net/oauth/v2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://yourapp.com/auth/callback"

Response:

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

Step 3: Refresh Tokens

When access tokens expire, use the refresh token:

Code
curl -X POST "https://auth.tech231apps.net/oauth/v2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"

Required Scopes

Include these scopes in your authentication requests:

Scope	Description	Required For
openid	OpenID Connect authentication	All requests
email	Access to user's email address	User info
profile	Access to user profile information	User info
offline_access	Request refresh token	Long-lived sessions
urn:zitadel:iam:org:project:id:321914919689650215:aud	Tech231 platform resource scope	API access
urn:zitadel:iam:user:resourceowner	Resource owner information	Multi-tenant apps

Minimum required scopes for API access:

Code
openid email profile urn:zitadel:iam:org:project:id:321914919689650215:aud

Understanding JWT Tokens

Token Structure

Tech231 Platform uses JWT (JSON Web Tokens) for authentication. A typical token contains:

Header:

Code
{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-id"
}

Payload (Claims):

Code
{
  "iss": "https://auth.tech231apps.net",
  "sub": "123456789012345678",
  "aud": ["321914919689650215"],
  "exp": 1705329600,
  "iat": 1705326000,
  "azp": "123456789012345678@your-org",
  "urn:zitadel:iam:org:id": "org_abc123xyz",
  "urn:zitadel:iam:org:project:id:321914919689650215:roles": {
    "SMS.Send": {
      "org_abc123xyz": "org_abc123xyz"
    }
  }
}

Key Claims:

• iss: Token issuer (Zitadel instance)
• sub: Subject (user/service account ID)
• aud: Audience (platform project ID)
• exp: Expiration timestamp
• azp: Authorized party (client ID)
• urn:zitadel:iam:org:id: Your organization/tenant ID
• urn:zitadel:iam:org:project:id:...:roles: Assigned roles

Tenant Context

Important: Your tenant context is automatically determined from the JWT token's organization claims. You do NOT need to send additional headers like X-Tenant-ID.

The platform extracts your tenant from:

Code
{
  "urn:zitadel:iam:org:id": "org_abc123xyz"
}

This ensures complete tenant isolation and security.

Security Best Practices

Credential Management

1. Never commit secrets to version control

   • Use environment variables
   • Use secret management tools (AWS Secrets Manager, Azure Key Vault, etc.)
   • Add .env files to .gitignore

2. Rotate credentials regularly

   • Change service account secrets every 90 days
   • Rotate immediately if compromised
   • Use multiple service accounts for different services

3. Use appropriate authentication method

   • Service accounts for backend APIs
   • User accounts for interactive applications
   • Never use user credentials in automated systems

Token Management

1. Store tokens securely

   • Use secure, HTTP-only cookies for web apps
   • Use encrypted storage for mobile apps
   • Never store in localStorage or sessionStorage

2. Implement token refresh

   • Refresh before expiration (not after)
   • Handle refresh failures gracefully
   • Redirect to login if refresh fails

3. Validate tokens

   • Verify signature using Zitadel's public keys
   • Check expiration (exp claim)
   • Validate audience (aud claim)
   • Verify issuer (iss claim)

Network Security

1. Always use HTTPS

   • Never send tokens over HTTP
   • Validate SSL certificates
   • Use certificate pinning for mobile apps

2. Implement rate limiting

   • Prevent brute force attacks
   • Limit token requests per IP
   • Monitor suspicious activity

Troubleshooting

"Invalid Client" Error

Cause: Client ID or secret is incorrect

Solution:

• Verify client ID matches exactly (including the @organization suffix)
• Regenerate client secret if lost
• Check for extra spaces or line breaks in credentials

"Invalid Scope" Error

Cause: Requesting scopes not granted to your organization

Solution:

• Verify granted projects in Zitadel
• Request correct platform resource scope
• Contact support to grant additional scopes

"Unauthorized" (401) Errors

Cause: Token expired or invalid

Solution:

• Check token expiration (exp claim)
• Implement token refresh
• Verify token is included in Authorization header
• Ensure format is Bearer <token>

"Forbidden" (403) Errors

Cause: Insufficient permissions

Solution:

• Check service user has required roles
• Verify authorization in Zitadel project
• Review role assignments
• Contact admin to grant necessary permissions

Token Not Working After Generation

Cause: Service user not authorized for platform APIs

Solution:

1. Go to Projects → Granted Projects → SMS
2. Check Authorizations
3. Add authorization for your service user
4. Include necessary roles

Code Examples

Node.js (Express)

Code
const axios = require('axios');

class ZitadelAuthClient {
  constructor(clientId, clientSecret) {
    this.clientId = clientId;
    this.clientSecret = clientSecret;
    this.tokenEndpoint = 'https://auth.tech231apps.net/oauth/v2/token';
    this.accessToken = null;
    this.expiresAt = null;
  }

  async getAccessToken() {
    // Return cached token if still valid
    if (this.accessToken && Date.now() < this.expiresAt) {
      return this.accessToken;
    }

    // Request new token
    const params = new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: this.clientId,
      client_secret: this.clientSecret,
      scope: 'openid email profile urn:zitadel:iam:org:project:id:321914919689650215:aud'
    });

    const response = await axios.post(this.tokenEndpoint, params, {
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
    });

    this.accessToken = response.data.access_token;
    this.expiresAt = Date.now() + (response.data.expires_in * 1000) - 60000; // 1min buffer

    return this.accessToken;
  }

  async makeAuthenticatedRequest(url, options = {}) {
    const token = await this.getAccessToken();
    
    return axios({
      ...options,
      url,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${token}`
      }
    });
  }
}

// Usage
const authClient = new ZitadelAuthClient(
  process.env.ZITADEL_CLIENT_ID,
  process.env.ZITADEL_CLIENT_SECRET
);

// Send SMS
const response = await authClient.makeAuthenticatedRequest(
  'https://api.tech231apps.net/v2/sms/send',
  {
    method: 'POST',
    data: {
      to: '+1234567890',
      from: 'YourBrand',
      message: 'Hello from Tech231!'
    }
  }
);

Python

Code
import requests
from datetime import datetime, timedelta

class ZitadelAuthClient:
    def __init__(self, client_id: str, client_secret: str):
        self.client_id = client_id
        self.client_secret = client_secret
        self.token_endpoint = 'https://auth.tech231apps.net/oauth/v2/token'
        self.access_token = None
        self.expires_at = None

    def get_access_token(self) -> str:
        # Return cached token if still valid
        if self.access_token and datetime.now() < self.expires_at:
            return self.access_token

        # Request new token
        response = requests.post(
            self.token_endpoint,
            data={
                'grant_type': 'client_credentials',
                'client_id': self.client_id,
                'client_secret': self.client_secret,
                'scope': 'openid email profile urn:zitadel:iam:org:project:id:321914919689650215:aud'
            },
            headers={'Content-Type': 'application/x-www-form-urlencoded'}
        )
        response.raise_for_status()
        
        data = response.json()
        self.access_token = data['access_token']
        self.expires_at = datetime.now() + timedelta(seconds=data['expires_in'] - 60)
        
        return self.access_token

    def make_authenticated_request(self, method: str, url: str, **kwargs):
        token = self.get_access_token()
        headers = kwargs.get('headers', {})
        headers['Authorization'] = f'Bearer {token}'
        kwargs['headers'] = headers
        
        return requests.request(method, url, **kwargs)

# Usage
auth_client = ZitadelAuthClient(
    os.environ['ZITADEL_CLIENT_ID'],
    os.environ['ZITADEL_CLIENT_SECRET']
)

# Send SMS
response = auth_client.make_authenticated_request(
    'POST',
    'https://api.tech231apps.net/v2/sms/send',
    json={
        'to': '+1234567890',
        'from': 'YourBrand',
        'message': 'Hello from Tech231!'
    }
)

C# (.NET)

Code
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text.Json;
using System.Threading.Tasks;

public class ZitadelAuthClient
{
    private readonly string _clientId;
    private readonly string _clientSecret;
    private readonly string _tokenEndpoint = "https://auth.tech231apps.net/oauth/v2/token";
    private string _accessToken;
    private DateTime _expiresAt;

    public ZitadelAuthClient(string clientId, string clientSecret)
    {
        _clientId = clientId;
        _clientSecret = clientSecret;
    }

    public async Task<string> GetAccessTokenAsync()
    {
        // Return cached token if still valid
        if (_accessToken != null && DateTime.UtcNow < _expiresAt)
        {
            return _accessToken;
        }

        using var client = new HttpClient();
        var content = new FormUrlEncodedContent(new[]
        {
            new KeyValuePair<string, string>("grant_type", "client_credentials"),
            new KeyValuePair<string, string>("client_id", _clientId),
            new KeyValuePair<string, string>("client_secret", _clientSecret),
            new KeyValuePair<string, string>("scope", "openid email profile urn:zitadel:iam:org:project:id:321914919689650215:aud")
        });

        var response = await client.PostAsync(_tokenEndpoint, content);
        response.EnsureSuccessStatusCode();

        var json = await response.Content.ReadAsStringAsync();
        var tokenResponse = JsonSerializer.Deserialize<TokenResponse>(json);

        _accessToken = tokenResponse.AccessToken;
        _expiresAt = DateTime.UtcNow.AddSeconds(tokenResponse.ExpiresIn - 60);

        return _accessToken;
    }

    public async Task<HttpResponseMessage> MakeAuthenticatedRequestAsync(
        HttpMethod method, 
        string url, 
        HttpContent content = null)
    {
        var token = await GetAccessTokenAsync();
        
        using var client = new HttpClient();
        var request = new HttpRequestMessage(method, url);
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
        
        if (content != null)
        {
            request.Content = content;
        }

        return await client.SendAsync(request);
    }

    private class TokenResponse
    {
        [JsonPropertyName("access_token")]
        public string AccessToken { get; set; }
        
        [JsonPropertyName("expires_in")]
        public int ExpiresIn { get; set; }
    }
}

// Usage
var authClient = new ZitadelAuthClient(
    Environment.GetEnvironmentVariable("ZITADEL_CLIENT_ID"),
    Environment.GetEnvironmentVariable("ZITADEL_CLIENT_SECRET")
);

// Send SMS
var smsData = new
{
    to = "+1234567890",
    from = "YourBrand",
    message = "Hello from Tech231!"
};

var jsonContent = new StringContent(
    JsonSerializer.Serialize(smsData),
    Encoding.UTF8,
    "application/json"
);

var response = await authClient.MakeAuthenticatedRequestAsync(
    HttpMethod.Post,
    "https://api.tech231apps.net/v2/sms/send",
    jsonContent
);

Next Steps

1. Test your authentication with the provided code examples
2. Implement token refresh for long-running applications
3. Set up error handling for authentication failures
4. Review security best practices and implement them
5. Monitor your API usage in the dashboard

Support

Need help with authentication setup?

• 📚 Documentation: OAuth 2.0 Guide
• 💬 Support Chat: Available in your dashboard
• 📧 Email: support@tech231apps.net
• 🎥 Video Tutorial: Watch the setup guide

---

Ready to authenticate? Create your service account now →