Users API

List and manage end users who have authenticated through your AuthGate project.

GET/api/v1/users

List users

Returns a paginated list of end users for your project. Users are created automatically when they authenticate through the proxy.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer your_api_key_here

Query parameters

Name
page
Type
integer
Description
Page number for pagination. Defaults to 1.
Name
limit
Type
integer
Description
Number of users per page. Defaults to 20.

Response

Name
data
Type
array
Description
Array of end user objects.
Name
pagination
Type
object
Description
Pagination metadata.
Name
pagination.page
Type
integer
Description
Current page number.
Name
pagination.limit
Type
integer
Description
Number of results per page.
Name
pagination.total
Type
integer
Description
Total number of users.
Name
pagination.totalPages
Type
integer
Description
Total number of pages.

User object fields

Name
id
Type
string
Description
Unique user identifier.
Name
email
Type
string | null
Description
The user's email address.
Name
name
Type
string | null
Description
The user's display name.
Name
avatarUrl
Type
string | null
Description
URL to the user's profile picture.
Name
lastAuthAt
Type
string | null
Description
ISO 8601 timestamp of the user's last authentication.
Name
createdAt
Type
string
Description
ISO 8601 timestamp when the user was first created.
Name
updatedAt
Type
string
Description
ISO 8601 timestamp when the user record was last updated.

Example request

curl https://auth.example.com/api/v1/users?page=1&limit=10 \
  -H "Authorization: Bearer your_api_key"

Example response

{
  "data": [
    {
      "id": "user_abc123",
      "email": "jane@example.com",
      "name": "Jane Doe",
      "avatarUrl": "https://avatars.githubusercontent.com/u/12345",
      "lastAuthAt": "2025-01-15T10:00:00.000Z",
      "createdAt": "2025-01-10T08:30:00.000Z",
      "updatedAt": "2025-01-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "totalPages": 5
  }
}

Error responses

Status	Description
`401`	Missing or invalid API key