Create an Application User

Overview

Create a new User (API key pair) for an Application. Users represent credentials for programmatic API access.

Resource Access

User Permissions: Admin users only
Endpoint: POST /applications/\{application_id}/users

Arguments

Parameter	Type	Required	Description
application_id	string	Yes	Application ID (in URL path)
tags	object	No	Custom key-value metadata

Example Request

curl -X POST \
  'https://api.ahrvo.network/payments/na/applications/APapplication123/users' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": {
      "environment": "production",
      "purpose": "web_checkout",
      "created_by": "admin@example.com"
    }
  }'

Example Response

{
  "id": "USuser456",
  "created_at": "2023-12-10T20:00:00Z",
  "updated_at": "2023-12-10T20:00:00Z",
  "enabled": true,
  "role": "ROLE_MERCHANT",
  "password": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tags": {
    "environment": "production",
    "purpose": "web_checkout",
    "created_by": "admin@example.com"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/users/USuser456"
    },
    "application": {
      "href": "https://api.ahrvo.network/payments/na/applications/APapplication123"
    }
  }
}

Additional Information

User as API Credentials: Users are API key pairs
- Username: The id field (e.g., "USuser456")
- Password: The password field (returned ONLY on creation)
- Use for HTTP Basic Authentication
- Required for all API requests
Password Security: CRITICAL
- Password shown ONLY once on creation
- Cannot be retrieved later
- Store securely immediately
- If lost, create new User
- Never commit to source control
- Use environment variables
Multiple Users: One Application can have many Users
- Different environments (dev, staging, prod)
- Different purposes (checkout, admin, reporting)
- Different team members
- Rotate keys without downtime
- Revoke individual keys
Enabled: Active status
- Created as enabled: true by default
- Can be disabled via PUT /users/{id}
- Disabled users cannot authenticate
- Use to revoke access temporarily
Role: Permission level
- ROLE_MERCHANT: Standard merchant access
  - Create transfers, manage payment instruments
  - Most common role
  - Used by merchants
- ROLE_PARTNER: Platform/partner access
  - Create merchants, applications
  - Platform-level operations
  - Higher privileges
Application ID: Parent application
- Users belong to specific Application
- Application links to Merchant
- Inherits Application's permissions
- Cannot move User to different Application
Tags: Custom metadata
- Track purpose, environment, creator
- Organize API keys
- Searchable and filterable
- Not used for authentication
Idempotency: Each request creates new User
- No duplicate detection
- Each call = new API key pair
- Different password each time
- Manage carefully to avoid key sprawl
No Expiration: Keys don't expire
- Valid until disabled or deleted
- Manual rotation required
- Best practice: Rotate periodically
- Disable old keys after rotation

Use Cases

Production API Keys

# Create keys for production environment
curl -X POST \
  'https://api.ahrvo.network/payments/na/applications/APapplication123/users' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": {
      "environment": "production",
      "purpose": "web_application",
      "server": "web-01",
      "created_at": "2023-12-10",
      "created_by": "devops@example.com"
    }
  }'

Tag with environment
Track which server uses keys
Record who created

Development/Testing Keys

# Create keys for development
curl -X POST \
  'https://api.ahrvo.network/payments/na/applications/APapplication123/users' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": {
      "environment": "development",
      "purpose": "local_testing",
      "developer": "john@example.com"
    }
  }'

Separate keys for dev/test
Lower risk if compromised
Easy to disable without affecting production

Service-Specific Keys

# Create keys for specific service
curl -X POST \
  'https://api.ahrvo.network/payments/na/applications/APapplication123/users' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": {
      "environment": "production",
      "service": "subscription_processor",
      "purpose": "recurring_billing",
      "team": "billing_team"
    }
  }'

Dedicated keys per microservice
Easier to track usage
Revoke without affecting other services

Key Rotation

# Create new keys for rotation
curl -X POST \
  'https://api.ahrvo.network/payments/na/applications/APapplication123/users' \
  -u username:password \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": {
      "environment": "production",
      "purpose": "web_application",
      "rotation_date": "2023-12-10",
      "replaces": "USolduser123"
    }
  }'

Create new keys
Tag with rotation info
Deploy new keys
Disable old keys after verification

Best Practices

Secure Storage: Store password immediately

// WRONG: Log password
console.log('Password:', user.password); // Never do this!

// RIGHT: Store securely
const response = await createUser(applicationId);
await storeInVault({
  username: response.id,
  password: response.password,
  environment: 'production'
});
// Never log or display password

Environment Variables: Use for deployment

# .env file (not committed to git)
Ahrvo Network_USERNAME=USuser456
Ahrvo Network_PASSWORD=a1b2c3d4-e5f6-7890-abcd-ef1234567890

# Use in application
const auth = {
  username: process.env.FINIX_USERNAME,
  password: process.env.FINIX_PASSWORD
};

Tag Thoroughly: Organize your keys
- environment: production, staging, development
- purpose: web_checkout, admin_panel, reporting
- created_by: Who created the key
- rotation_date: When to rotate
- expires_at: Manual expiration tracking
Key Rotation: Rotate regularly
- Best practice: Every 90 days
- Create new User
- Deploy new credentials
- Test thoroughly
- Disable old User
- Don't delete immediately (allow rollback)
Separate Keys: Don't share
- Different environments = different keys
- Different services = different keys
- Different developers = different keys
- Easier to track and revoke
Monitor Usage: Track which keys are used
- Tag with service/server
- Monitor API calls
- Detect unused keys
- Disable inactive keys
Principle of Least Privilege: Minimal permissions
- Use ROLE_MERCHANT unless ROLE_PARTNER needed
- Create Application-specific Users
- Revoke when no longer needed

Common Workflows

Initial Setup

Create Application (one-time)
Create User for production
Store credentials securely
Configure application with credentials
Test authentication
Deploy to production

Key Rotation Workflow

async function rotateApiKeys(applicationId, oldUserId) {
  // 1. Create new User
  const newUser = await createUser(applicationId, {
    tags: {
      environment: 'production',
      rotation_date: new Date().toISOString(),
      replaces: oldUserId
    }
  });
  
  // 2. Store new credentials securely
  await storeInVault({
    username: newUser.id,
    password: newUser.password
  });
  
  // 3. Update application configuration
  await updateConfig({
    FINIX_USERNAME: newUser.id,
    FINIX_PASSWORD: newUser.password
  });
  
  // 4. Deploy new configuration
  await deployToProduction();
  
  // 5. Wait for deployment to complete
  await waitForHealthCheck();
  
  // 6. Verify new keys working
  const testResult = await testApiAccess(newUser.id);
  
  if (testResult.success) {
    // 7. Disable old User
    await updateUser(oldUserId, { enabled: false });
    
    console.log('Key rotation successful');
    console.log('Old user disabled:', oldUserId);
    console.log('New user active:', newUser.id);
  } else {
    // Rollback if issues
    console.error('Key rotation failed, keeping old keys');
  }
}

Multi-Environment Setup

// Create keys for each environment
const environments = ['development', 'staging', 'production'];

for (const env of environments) {
  const user = await createUser(applicationId, {
    tags: {
      environment: env,
      purpose: 'web_application',
      created_at: new Date().toISOString()
    }
  });
  
  // Store in environment-specific vault/config
  await storeCredentials(env, {
    username: user.id,
    password: user.password
  });
  
  console.log(`${env} keys created: ${user.id}`);
}

Compromised Key Response

Create new User immediately
Store new credentials
Update application with new keys
Deploy as emergency hotfix
Disable compromised User
Audit API logs for suspicious activity
Notify security team
Document incident

Security Considerations

Password Visibility: Only shown once
- Cannot retrieve later
- Copy immediately after creation
- Store in secure vault (HashiCorp Vault, AWS Secrets Manager, etc.)
- Never email or Slack credentials
Access Control: Limit who can create Users
- Only admin/devops team
- Log all User creation
- Audit regularly
- Review active Users
Credential Leakage: Prevention
- Never commit to git
- Use .gitignore for .env files
- Scan code for hardcoded credentials
- Rotate if accidentally exposed
- Use secret scanning tools
Regular Audits: Review active Users
- List all Users
- Check last used date (via logs)
- Disable unused Users
- Remove old/test keys
- Quarterly reviews recommended

GET /users: List all Users
GET /users/{id}: Fetch User details
PUT /users/{id}: Update User (disable, update tags)
GET /applications/{id}: View parent Application

Overview​

Resource Access​

Arguments​

Example Request​

Example Response​

Additional Information​

Use Cases​

Production API Keys​

Development/Testing Keys​

Service-Specific Keys​

Key Rotation​

Best Practices​

Common Workflows​

Initial Setup​

Key Rotation Workflow​

Multi-Environment Setup​

Compromised Key Response​

Security Considerations​

Related Endpoints​