Skip to main content

API FAQ & Troubleshooting

Common questions and solutions for Access Control API integration.

Authentication issues​

Why am I getting 401 Unauthorized?​

Possible causes:

  1. Token expired - Access tokens expire after 1 hour. Use the refresh token to get a new one.
  2. Invalid token - Ensure the token is correctly formatted and not corrupted.
  3. Wrong audience - Tokens are audience-specific. Admin UI requires control-admin audience.
  4. Missing header - Include Authorization: Bearer <token> header.

Solution:

# Refresh your token
curl -X POST https://idp.digiwedge.com/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "your-refresh-token"}'

Why am I getting 403 Forbidden?​

Your user lacks the required capability. Check:

  1. User has the correct role assigned
  2. Role has the required permission
  3. You're accessing the correct tenant

Debug with:

curl -X POST https://access-control-api.digiwedge.com/api/v1/capabilities/can \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"checks": [{"feature": "USER_MGMT", "action": "read"}]}'

How do I handle MFA during login?​

When login returns mfaRequired: true:

  1. Store the mfaToken and userId from the response
  2. Prompt user for their MFA code
  3. Call /auth/mfa/verify-login with the code
if (loginResponse.mfaRequired) {
  const code = await promptUserForCode();
  const result = await fetch('/auth/mfa/verify-login', {
    method: 'POST',
    body: JSON.stringify({
      userId: loginResponse.userId,
      code: code,
      rememberDevice: true,
    }),
  });
}

API integration​

Which tenant ID should I use?​

Use the tenant ID for the organization you're operating on. You can find this in:

  • The JWT claims under tenants array
  • Your organization's admin portal
  • The response from GET /api/v1/tenants (if you have access)

How do I paginate large result sets?​

All list endpoints support pagination:

GET /api/v1/users?page=1&limit=50

Response includes:

{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 150,
    "totalPages": 3
  }
}

Why are my CORS requests failing?​

Browser requests from unlisted origins are blocked. Contact your administrator to add your domain to CORS_ALLOWED_ORIGINS.

Symptoms:

  • Preflight (OPTIONS) requests fail
  • Console shows CORS policy errors

How do I use the TypeScript client in Node.js?​

import { Configuration, UsersApi } from '@digiwedge/access-control-api-client';

const config = new Configuration({
  basePath: process.env.AC_API_URL,
  accessToken: async () => {
    // Return your access token
    return await getServiceAccountToken();
  },
});

const api = new UsersApi(config);
const users = await api.getUsers({ page: 1, limit: 20 });

User management​

How do I invite a user to multiple tenants?​

Send separate invitations for each tenant:

# Invitation for Tenant A
curl -X POST /api/v1/invitations \
  -H "x-tenant-id: tenant-a-id" \
  -d '{"email": "user@example.com", "roleIds": ["role-1"]}'

# Invitation for Tenant B
curl -X POST /api/v1/invitations \
  -H "x-tenant-id: tenant-b-id" \
  -d '{"email": "user@example.com", "roleIds": ["role-2"]}'

Can I restore a deleted user?​

Yes, soft-deleted users can be restored:

POST /api/v1/users/:userId/restore

Note: Users must be restored within the retention period. Permanently deleted users cannot be recovered.

How do I force a user to re-authenticate?​

Revoke all their sessions:

POST /api/v1/users/:userId/sessions/revoke-all

Permissions​

What's the difference between roles and permissions?​

  • Permissions define what actions are allowed (e.g., "can read users")
  • Roles are collections of permissions (e.g., "Admin" role has many permissions)
  • Users are assigned roles, inheriting all their permissions

How do I check if a user can perform an action?​

Use the capabilities endpoint:

POST /api/v1/capabilities/can
{
  "checks": [
    { "feature": "USER_MGMT", "action": "delete" }
  ]
}

Response:

{
  "results": [
    { "feature": "USER_MGMT", "action": "delete", "allowed": true }
  ]
}

Why does my custom role not have expected permissions?​

Verify:

  1. Permission assignments exist for the role
  2. Permissions reference correct features
  3. User has the role assigned in the correct tenant