API Client Registration

What are API Clients?

API clients are applications that interact with the Exepron REST API on behalf of users or systems. Each client must be registered in the Exepron Identity Server to obtain credentials for authentication.

Key Concepts

When You Need an API Client

• Building a web application that integrates with Exepron
• Creating a mobile app for project management
• Developing automated scripts or services
• Integrating Exepron with other business systems
• Building custom dashboards or reporting tools

Client Types

Exepron provides three simplified templates for creating API clients. Choose the template that best matches your use case:

exepron_pat_[client-id]:[secret]

Example:
exepron_pat_abc123def456:dGVzdHNlY3JldA==

Comparison Table

Step-by-Step Registration Guide

Follow these steps to create API clients in the Exepron Identity Server:

1

Access API Client Management

Navigate to the Exepron Identity Server and log in:

https://{YOUR_IDENTITY_SERVER}

Then access the API Client Management page via your profile settings.

2

Choose Client Template

Select one of the three available templates based on your use case:

• Personal Access Token: For testing and scripts
• Backend Service: For server-to-server integration
• Web/Mobile App: For user-facing applications

Creating a Personal Access Token

1

Fill in Token Details

Provide the following information:

• Token Name: A descriptive name (e.g., "Local Development Testing")
• Token Expiration: Choose from 30 days, 90 days, 1 year, or never

2

Copy Your Token

After creation, copy your token immediately - it won't be shown again:

exepron_pat_abc123def456:dGVzdHNlY3JldA==

⚠️ Store this token securely!
It won't be shown again.

Usage: Use this token as a Bearer token in the Authorization header:

curl -H "Authorization: Bearer exepron_pat_abc123def456:dGVzdHNlY3JldA==" \
  https://{YOUR_API_SERVER}/odata/Projects

Creating a Backend Service

Client ID: service_abc123def456
Client Secret: dGVzdHNlY3JldA==

⚠️ Store these credentials securely!
The secret won't be shown again.

POST https://{YOUR_IDENTITY_SERVER}/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=password
&username=USER_EMAIL
&password=USER_PASSWORD
&client_id=service_abc123def456
&client_secret=dGVzdHNlY3JldA==
&scope=exepron.restapi

Creating a Web/Mobile App

Client ID: app_abc123def456
Grant Type: Authorization Code + PKCE
Redirect URIs:
- https://app.example.com/callback
- http://localhost:3000/callback

Client Configuration Options

Essential Settings

Configuration Examples

Single Page Application (SPA)

{
  "clientId": "spa-client",
  "clientName": "React Dashboard",
  "clientType": "public",
  "grantTypes": ["authorization_code"],
  "redirectUris": [
    "https://app.example.com/callback",
    "http://localhost:3000/callback"
  ],
  "postLogoutRedirectUris": [
    "https://app.example.com",
    "http://localhost:3000"
  ],
  "allowedCorsOrigins": [
    "https://app.example.com",
    "http://localhost:3000"
  ],
  "requirePkce": true,
  "allowOfflineAccess": true,
  "scopes": ["openid", "profile", "api1", "offline_access"]
}

Mobile Application

{
  "clientId": "mobile-app",
  "clientName": "Exepron Mobile",
  "clientType": "public",
  "grantTypes": ["authorization_code"],
  "redirectUris": [
    "com.exepron.mobile://callback",
    "exepron://oauth/redirect"
  ],
  "requirePkce": true,
  "allowOfflineAccess": true,
  "refreshTokenLifetime": 7776000,  // 90 days for mobile
  "scopes": ["openid", "profile", "api1", "offline_access"]
}

Backend Service

{
  "clientId": "backend-service",
  "clientName": "Data Sync Service",
  "clientType": "confidential",
  "grantTypes": ["password"],
  "clientSecrets": [
    {
      "value": "supersecret123",
      "expiration": "2026-01-01"
    }
  ],
  "scopes": ["api1"],
  "claims": [
    {
      "type": "service",
      "value": "data-sync"
    }
  ]
}

Redirect URI Configuration

URI Requirements

• Must be absolute URIs (not relative paths)
• HTTPS required for production (HTTP allowed only for localhost)
• Exact match required (no wildcards in production)
• Case-sensitive matching
• Query strings and fragments not allowed

Common Redirect URI Patterns

# Production
https://app.example.com/auth/callback
https://app.example.com/silent-renew

# Staging
https://staging.example.com/auth/callback

# Development
http://localhost:3000/auth/callback
http://localhost:4200/auth/callback
http://127.0.0.1:8080/callback

# iOS (Custom Scheme)
com.example.app://oauth/callback
com.example.app://auth/redirect

# iOS (Universal Links)
https://app.example.com/ios/oauth/callback

# Android (Custom Scheme)
com.example.app://oauth/redirect

# Android (App Links)
https://app.example.com/android/oauth/callback

# Loopback for native apps
http://localhost/callback
http://127.0.0.1:PORT/callback

# Custom protocol
myapp://auth/callback

Silent Token Renewal

For SPAs, configure a separate URI for silent token renewal:

// Main callback
https://app.example.com/callback

// Silent renewal frame
https://app.example.com/silent-renew.html

Scopes Assignment

Understanding Scopes

Scopes define what resources and operations your client can access. Follow the principle of least privilege - only request scopes you actually need.

Available Scopes

Scope Combinations

Common scope combinations for different use cases:

# Read-only dashboard
scopes: ["openid", "profile", "api1.read"]

# Full-featured web app
scopes: ["openid", "profile", "email", "api1", "offline_access"]

# Backend service
scopes: ["api1"]

# Mobile app with offline support
scopes: ["openid", "profile", "api1", "offline_access"]

# Reporting tool
scopes: ["projects.read", "tasks.read", "reports"]

Client Secrets Management

Generating Secrets

Client secrets are automatically generated when creating confidential clients. You can also generate new secrets manually:

# Generate a secure secret (example)
openssl rand -hex 32
# Output: 7f3d8c2a9b5e4f1d8a6c3e2f9d5b7a1c4e8f2a5d7b9c3e6f8a2d5e8b1c4f7a9d

Secret Rotation

Regularly rotate client secrets for security:

Storing Secrets Securely

Environment Variable Example

# .env file (add to .gitignore!)
EXEPRON_CLIENT_ID=web-dashboard-prod
EXEPRON_CLIENT_SECRET=7f3d8c2a9b5e4f1d8a6c3e2f9d5b7a1c

# Node.js usage
const clientId = process.env.EXEPRON_CLIENT_ID;
const clientSecret = process.env.EXEPRON_CLIENT_SECRET;

# .NET usage
var clientId = Configuration["Exepron:ClientId"];
var clientSecret = Configuration["Exepron:ClientSecret"];

# Python usage
import os
client_id = os.environ.get('EXEPRON_CLIENT_ID')
client_secret = os.environ.get('EXEPRON_CLIENT_SECRET')

Managing Existing Clients

Viewing Your API Clients

Access the API Client Management page to view all your clients:

• Client Name and ID
• Client Type (Personal Token, Backend Service, Web/Mobile App)
• Grant Types and Scopes
• Creation date and last accessed date
• Active/Inactive status

Editing Clients

You can update certain properties of existing API clients. The editable fields depend on the client type:

Web/Mobile App Clients:

• Display Name: Update the application name (3-200 characters)
• Description: Update or add an optional description
• Redirect URIs: Modify callback URLs for authentication (one per line)

Backend Service Clients:

• Display Name: Update the service name
• Description: Update or add an optional description

Personal Access Tokens:

• Display Name: Update the token name

To edit a client:

1. Navigate to the API Client Management page
2. Find the client you want to edit
3. Click the Edit button (pencil icon)
4. Modify the desired fields in the edit modal
5. Click "Save Changes"

Regenerating Client Secrets

If you need to rotate or regenerate a client secret:

1. Navigate to the API Client Management page
2. Find the client you want to update
3. Click the "Regenerate Secret" button
4. Copy the new secret immediately (it won't be shown again)
5. Update your application with the new secret

Secret Rotation Best Practices:

• Rotate secrets regularly (every 90-180 days)
• Set calendar reminders for secret expiration dates
• Test with new secret before revoking old one (if possible)
• Keep a secure backup of active secrets
• Document which services use which clients

Deactivating Clients

Temporarily disable a client without deletion:

1. Navigate to the API Client Management page
2. Find the client you want to deactivate
3. Click the "Deactivate" button
4. Deactivated clients cannot authenticate until reactivated

Client Limit

Each account is limited to 10 active API clients. To create new clients after reaching the limit:

• Deactivate unused clients
• Delete clients that are no longer needed
• Consolidate multiple clients if possible

Monitoring Client Usage

Track when your clients were last used:

• Created On: When the client was first created
• Last Used On: When the client last successfully authenticated

Use this information to identify unused clients that can be safely deactivated or deleted.

Best Practices

myapp-dev     → Development
myapp-staging → Staging
myapp-prod    → Production

Format: [app]-[platform]-[environment]
Examples:
- dashboard-web-prod
- mobile-ios-staging
- sync-service-dev

# Too broad
scopes: ["api1", "admin"]

# Better
scopes: ["projects.read", "tasks.read"]

Troubleshooting

Additional Resources

• Authentication Guide - Complete OAuth 2.0 flow documentation
• Getting Started - Make your first API call
• OAuth 2.0 Specification
• OpenID Connect Documentation
• Contact Support