Authentication

The de.iterate SDK supports multiple authentication methods for different use cases.

API Tokens

API tokens are the recommended way to authenticate server-side applications.

Creating an API Token

1. Log in to your de.iterate dashboard
2. Navigate to Settings → API Tokens
3. Click Create Token
4. Select the appropriate access level and permissions
5. Copy the token (it won't be shown again!)

Using API Tokens

import { DeIterateClient } from '@deiterate/sdk';

const client = new DeIterateClient({
  apiKey: 'deit_your_api_token_here',
  organizationId: 'your-org-id',
});

Token Prefixes

Prefix	Type	Description
deit_	API Token	Standard API token for applications
deit_sa_	Service Account	Cross-tenancy service account token

Service Accounts

Service accounts provide elevated access for administrative operations across multiple tenancies.

WARNING

Service accounts have powerful permissions. Use them carefully and always follow the principle of least privilege.

Service Account Features

• Cross-tenancy access - Access multiple organizations with a single token
• IP allowlisting - Restrict access to specific IP addresses
• Audit logging - All actions are logged for compliance
• Expiration - Tokens can have configurable expiration

Using Service Accounts

import { DeIterateClient } from '@deiterate/sdk';

const client = new DeIterateClient({
  apiKey: 'deit_sa_your_service_account_token',
  // organizationId is set per-request for service accounts
});

// Access a specific organization
const risks = await client.risks.list({
  headers: { 'X-Tenancy-Id': 'target-org-id' }
});

Token Permissions

Access Types

Type	Description
full	Complete access to all resources
granular	Fine-grained per-resource permissions

Permission Levels

For granular tokens, permissions are defined per resource:

{
  permissions: [
    { resource: 'risks', actions: ['read', 'write'] },
    { resource: 'controls', actions: ['read'] },
    { resource: 'tasks', actions: ['read', 'write', 'delete'] },
  ]
}

Available Actions

Action	Description
read	View resources (GET requests)
write	Create and update resources (POST, PUT, PATCH)
delete	Delete resources (DELETE requests)

Security Best Practices

Environment Variables

Never hardcode API tokens. Use environment variables:

// ✅ Good
const client = new DeIterateClient({
  apiKey: process.env.DEITERATE_API_KEY!,
  organizationId: process.env.DEITERATE_ORG_ID!,
});

// ❌ Bad - Never do this!
const client = new DeIterateClient({
  apiKey: 'deit_actual_token_here',
  organizationId: 'actual-org-id',
});

Token Rotation

Rotate your API tokens regularly:

1. Create a new token
2. Update your application to use the new token
3. Verify the new token works
4. Revoke the old token

Minimal Permissions

Use the principle of least privilege:

// ✅ Good - Only request permissions you need
{
  permissions: [
    { resource: 'risks', actions: ['read'] },
  ]
}

// ❌ Avoid - Don't use full access if you only need read
{
  accessType: 'full'
}

IP Allowlisting

For service accounts, always configure IP allowlists in production:

# Create service account with IP restrictions
./service-account-cli.ts create \
  --name "Production API" \
  --ips "10.0.0.1,10.0.0.2"

Error Handling

Handle authentication errors gracefully:

import { 
  DeIterateClient, 
  AuthenticationError,
  AuthorizationError 
} from '@deiterate/sdk';

try {
  const risks = await client.risks.list();
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid or expired API token');
    // Prompt for re-authentication or use refresh token
  } else if (error instanceof AuthorizationError) {
    console.error('Insufficient permissions for this action');
    // Request elevated permissions
  }
}

Next Steps

• Error Handling - Handle all error types