User API

The Guardhouse User API allows you to programmatically manage users in your Guardhouse instance. This API is used for administrative operations and requires valid authentication credentials using Client ID and Client Secret.

Authentication

To authenticate with the Management API, use your Client ID and Client Secret to obtain an access token via the Client Credentials flow.

Getting an Access Token

Endpoint: POST /oauth/token

curl -X POST https://your_tenant.guardhouse.cloud/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "audience=https://your_tenant.guardhouse.cloud/api/v2"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:users write:users delete:users"
}

Using the Access Token

Include the access token in the Authorization header for all API requests:

curl -X GET https://your_tenant.guardhouse.cloud/api/v2/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Base URL

All API requests should be made to:

https://your_tenant.guardhouse.cloud/api/v2

Replace your-tenant with your actual Guardhouse tenant domain.

User Management

Get Users List

Retrieve a paginated list of all users in your tenant.

Endpoint: GET /users

Query Parameters:

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
per_page	integer	No	Items per page (default: 50, max: 100)
sort	string	No	Sort field (e.g., email, name, created_at)
order	string	No	Sort order: asc or desc (default: asc)
email	string	No	Filter by email (partial match)
query	string	No	Search by name or email

Example Request:

curl -X GET "https://your_tenant.guardhouse.cloud/api/v2/users?page=1&per_page=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "users": [
    {
      "user_id": "usr_123456789",
      "email": "john.doe@example.com",
      "name": "John Doe",
      "picture": "https://cdn.example.com/avatars/john.jpg",
      "connection": "Username-Password-Authentication",
      "email_verified": true,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:45:00Z",
      "last_login": "2024-01-20T09:15:00Z",
      "logins_count": 5
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 50,
  "total_pages": 1
}

Get User by ID

Retrieve detailed information about a specific user.

Endpoint: GET /users/{user_id}

Path Parameters:

Parameter	Type	Required	Description
user_id	string	Yes	The unique user ID

Example Request:

curl -X GET https://your_tenant.guardhouse.cloud/api/v2/users/usr_123456789 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "user_id": "usr_123456789",
  "email": "john.doe@example.com",
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "nickname": "johndoe",
  "picture": "https://cdn.example.com/avatars/john.jpg",
  "connection": "Username-Password-Authentication",
  "email_verified": true,
  "phone_number": "+1-555-123-4567",
  "phone_verified": true,
  "user_metadata": {
    "department": "Engineering",
    "employee_id": "EMP001"
  },
  "app_metadata": {
    "roles": ["admin"],
    "permissions": ["read:all", "write:users"]
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:45:00Z",
  "last_login": "2024-01-20T09:15:00Z",
  "logins_count": 5,
  "identities": [
    {
      "user_id": "usr_123456789",
      "provider": "auth0",
      "connection": "Username-Password-Authentication",
      "isSocial": false
    }
  ],
  "multifactor": [
    "guardhouse-otp"
  ],
  "blocked": false,
  "email": "john.doe@example.com"
}

Update User

Update information for a specific user.

Endpoint: PATCH /users/{user_id}

Path Parameters:

Parameter	Type	Required	Description
user_id	string	Yes	The unique user ID

Request Body:

{
  "email": "new.email@example.com",
  "name": "John Updated Doe",
  "given_name": "John",
  "family_name": "Updated Doe",
  "nickname": "johndoe",
  "picture": "https://cdn.example.com/avatars/new-john.jpg",
  "email_verified": true,
  "phone_number": "+1-555-987-6543",
  "phone_verified": true,
  "user_metadata": {
    "department": "Marketing",
    "employee_id": "EMP002"
  },
  "app_metadata": {
    "roles": ["user"],
    "permissions": ["read:users"]
  },
  "blocked": false,
  "connection": "Username-Password-Authentication",
  "password": "NewSecurePassword123!",
  "verify_email": false,
  "verify_phone": false
}

Example Request:

curl -X PATCH https://your_tenant.guardhouse.cloud/api/v2/users/usr_123456789 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new.email@example.com",
    "name": "John Updated Doe"
  }'

Response:

{
  "user_id": "usr_123456789",
  "email": "new.email@example.com",
  "name": "John Updated Doe",
  "email_verified": true,
  "updated_at": "2024-01-25T16:20:00Z"
}

Delete User

Delete a user from your tenant.

Endpoint: DELETE /users/{user_id}

Path Parameters:

Parameter	Type	Required	Description
user_id	string	Yes	The unique user ID

Example Request:

curl -X DELETE https://your_tenant.guardhouse.cloud/api/v2/users/usr_123456789 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "message": "User deleted successfully"
}

Current User Profile Management

These endpoints allow the authenticated user to manage their own profile.

Get Current User Profile

Retrieve the profile of the currently authenticated user.

Endpoint: GET /users/me

Example Request:

curl -X GET https://your_tenant.guardhouse.cloud/api/v2/users/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "user_id": "usr_123456789",
  "email": "john.doe@example.com",
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "nickname": "johndoe",
  "picture": "https://cdn.example.com/avatars/john.jpg",
  "email_verified": true,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:45:00Z"
}

Update Current User Password

Change the password of the currently authenticated user.

Endpoint: POST /users/me/password

Request Body:

{
  "current_password": "OldPassword123!",
  "new_password": "NewSecurePassword123!",
  "confirm_password": "NewSecurePassword123!"
}

Example Request:

curl -X POST https://your_tenant.guardhouse.cloud/api/v2/users/me/password \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "OldPassword123!",
    "new_password": "NewSecurePassword123!",
    "confirm_password": "NewSecurePassword123!"
  }'

Response:

{
  "message": "Password updated successfully"
}

Error Response (Invalid Current Password):

{
  "code": "invalid_password",
  "message": "Current password is incorrect"
}

Update Current User Name

Update the name of the currently authenticated user.

Endpoint: PATCH /users/me/name

Request Body:

{
  "name": "John Updated Doe",
  "given_name": "John",
  "family_name": "Updated Doe"
}

Example Request:

curl -X PATCH https://your_tenant.guardhouse.cloud/api/v2/users/me/name \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Updated Doe",
    "given_name": "John",
    "family_name": "Updated Doe"
  }'

Response:

{
  "message": "Name updated successfully",
  "user": {
    "name": "John Updated Doe",
    "given_name": "John",
    "family_name": "Updated Doe"
  }
}

Update Current User Email

Update the email address of the currently authenticated user. This may require email verification.

Endpoint: PATCH /users/me/email

Request Body:

{
  "email": "new.email@example.com",
  "verify_email": true
}

Example Request:

curl -X PATCH https://your_tenant.guardhouse.cloud/api/v2/users/me/email \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new.email@example.com",
    "verify_email": true
  }'

Response:

{
  "message": "Email change requested. Please verify your new email address.",
  "email": "new.email@example.com",
  "email_verified": false
}

Update Current User Profile

Update multiple profile fields at once.

Endpoint: PATCH /users/me

Request Body:

{
  "name": "John Updated Doe",
  "nickname": "johndoe_new",
  "picture": "https://cdn.example.com/avatars/new-john.jpg",
  "user_metadata": {
    "department": "Marketing",
    "location": "New York"
  }
}

Example Request:

curl -X PATCH https://your_tenant.guardhouse.cloud/api/v2/users/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Updated Doe",
    "nickname": "johndoe_new",
    "picture": "https://cdn.example.com/avatars/new-john.jpg"
  }'

Response:

{
  "user_id": "usr_123456789",
  "email": "john.doe@example.com",
  "name": "John Updated Doe",
  "nickname": "johndoe_new",
  "picture": "https://cdn.example.com/avatars/new-john.jpg",
  "updated_at": "2024-01-25T16:20:00Z"
}

Error Responses

All API errors follow a consistent format:

{
  "code": "ERROR_CODE",
  "message": "Human-readable error message",
  "details": {
    "field": "Additional error details"
  }
}

Common Error Codes

Code	Status	Description
invalid_token	401	Access token is invalid or expired
insufficient_scope	403	Token lacks required permissions
user_not_found	404	User does not exist
invalid_password	400	Current password is incorrect
password_too_weak	400	New password does not meet requirements
email_already_exists	409	Email address is already in use
validation_error	422	Request validation failed

Rate Limiting

The API is rate-limited to prevent abuse. Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1640995200

When rate limit is exceeded:

{
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please try again later.",
  "retry_after": 3600
}

SDKs

For easier integration with User API, we provide official SDKs:

• .NET SDK

See the SDKs documentation for complete client-side authentication and token management.

See the SDKs section for detailed usage examples.

Best Practices

1. Always use HTTPS: Never send credentials over unencrypted connections
2. Validate tokens: Always validate access tokens before processing requests
3. Use pagination: For large datasets, use pagination to avoid timeouts
4. Cache responses: Cache frequently accessed user data to reduce API calls
5. Handle errors gracefully: Implement proper error handling and retry logic
6. Rotate credentials: Regularly rotate Client Secrets for security
7. Monitor usage: Track API usage to detect anomalies

Example: Full User Management Workflow

// 1. Get access token
var token = await GetAccessTokenAsync(clientId, clientSecret);

// 2. List users
var users = await GetUsersAsync(token, page: 1, perPage: 50);

// 3. Get specific user
var user = await GetUserAsync(token, users.First().UserId);

// 4. Update user
var updatedUser = await UpdateUserAsync(token, user.UserId, new {
    name = "Updated Name"
});

// 5. Update current user profile
await UpdateCurrentUserProfileAsync(token, new {
    name = "My New Name"
});

// 6. Change password
await ChangePasswordAsync(token, "OldPass", "NewPass");

For detailed API reference and additional endpoints, see the Errors & Status Codes section.