Skip to content

UsersController API Documentation

Jump to bottom
Lee Sambridge edited this page Mar 21, 2025 · 1 revision

Users API Documentation

This document provides documentation for the Users API endpoints available in the Points.Api system.

Table of Contents

Authentication

All endpoints in this API require JWT Bearer authentication (except for GetUserDetails which has its own authentication mechanism). Include a valid JWT token in the Authorization header of your requests.

Authorization: Bearer {your_jwt_token}

Endpoints

Get User

Retrieves a user by their ID.

URL: /api/Users/{userId}

Method: GET

Auth required: Yes (JWT Bearer)

URL Parameters:

  • userId (long) - The ID of the user to retrieve

Success Response:

Example Request:

GET /api/Users/123 HTTP/1.1
Host: your-api-domain.com
Authorization: Bearer {your_jwt_token}

Example Response:

{
  "id": 123,
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "username": "johndoe",
  "dateJoined": "2024-01-15T08:30:00Z",
  "isActive": true,
  "partnerId": 456,
  "pointSets": [
    {
      "id": 789,
      "dateCreated": "2025-03-15T10:30:00Z",
      "description": "Running activity",
      "points": [
        {
          "id": 101,
          "totalPointValue": 100,
          "totalPointsUsed": 0
        }
      ]
    }
  ],
  "competitionsEntered": 5,
  "leaderBoardsEntered": 3,
  "rewardsUnlocked": 2
}

Get User By API Key and Slug

Retrieves a user by their API key and slug.

URL: /api/Users/{apiKey}/slug/{slug}

Method: GET

Auth required: Yes (JWT Bearer)

URL Parameters:

  • apiKey (string) - The API key associated with the user
  • slug (string) - The slug identifier

Success Response:

Example Request:

GET /api/Users/abc123def456/slug/user-profile HTTP/1.1
Host: your-api-domain.com
Authorization: Bearer {your_jwt_token}

Example Response:

{
  "id": 123,
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "username": "johndoe",
  "dateJoined": "2024-01-15T08:30:00Z",
  "isActive": true,
  "partnerId": 456
}

Get User By API Key (Raw)

Retrieves a user by their API key.

URL: /api/Users/{apiKey}/raw

Method: GET

Auth required: Yes (JWT Bearer)

URL Parameters:

  • apiKey (string) - The API key associated with the user

Success Response:

Example Request:

GET /api/Users/abc123def456/raw HTTP/1.1
Host: your-api-domain.com
Authorization: Bearer {your_jwt_token}

Example Response:

{
  "id": 123,
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "username": "johndoe",
  "dateJoined": "2024-01-15T08:30:00Z",
  "isActive": true,
  "partnerId": 456
}

Get User By Keys

Retrieves a user by their API key and magic key.

URL: /api/Users/{apikey}/{magickey}

Method: GET

Auth required: Yes (JWT Bearer)

URL Parameters:

  • apikey (string) - The API key associated with the user
  • magickey (string) - The magic key for authentication

Success Response:

  • Code: 200 OK
  • Content: User data with leaderboard information

Example Request:

GET /api/Users/abc123def456/xyz789magic HTTP/1.1
Host: your-api-domain.com
Authorization: Bearer {your_jwt_token}

Example Response:

{
  "id": 123,
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "leaderboards": [
    {
      "id": 1,
      "name": "Monthly Running Challenge",
      "position": 3,
      "points": 250
    }
  ]
}

Get User Details

Retrieves user details and generates a JWT token. This endpoint uses a custom authentication mechanism.

URL: /api/Users/{userRawId}/details

Method: GET

Auth required: No (Custom authentication)

URL Parameters:

  • userRawId (string) - The raw user ID in the format userId$timestamp

Success Response:

  • Code: 200 OK
  • Content: JWT token

Example Request:

GET /api/Users/123$1616969696969/details HTTP/1.1
Host: your-api-domain.com

Example Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Notes:

  • The userRawId parameter must be in the format userId$timestamp where timestamp is the number of milliseconds since January 1, 1970 (Unix epoch).
  • The request must be made within 10 seconds of the timestamp in the userRawId parameter.
  • The user ID must correspond to a valid user in the system.
  • The user must be associated with a valid partner.

Update User

Updates a user's information.

URL: /api/Users

Method: PATCH

Auth required: Yes (JWT Bearer)

Request Body:

Success Response:

  • Code: 200 OK
  • Content: Success message

Example Request:

PATCH /api/Users HTTP/1.1
Host: your-api-domain.com
Authorization: Bearer {your_jwt_token}
Content-Type: application/json

{
  "id": 123,
  "firstName": "John",
  "lastName": "Doe",
  "emailAddress": "john.doe@example.com",
  "birthYear": 1985,
  "gender": "Male",
  "countryId": 1
}

Example Response:

"User updated successfully"

Upgrade User

Upgrades a user to a new level based on partner points.

URL: /api/Users/{userId}/upgrade/{partnerPointsId}

Method: PUT

Auth required: Yes (JWT Bearer)

URL Parameters:

  • userId (long) - The ID of the user to upgrade
  • partnerPointsId (long) - The ID of the partner points to use for the upgrade

Success Response:

  • Code: 200 OK
  • Content: Boolean indicating success

Example Request:

PUT /api/Users/123/upgrade/456 HTTP/1.1
Host: your-api-domain.com
Authorization: Bearer {your_jwt_token}

Example Response:

true

Models

UserUpdateModel

The UserUpdateModel is used to update a user's information.

Property Type Description
id long Unique identifier for the user
firstName string First name of the user
lastName string Last name of the user
emailAddress string Email address of the user
birthYear int Birth year of the user
gender string Gender of the user
countryId long? ID of the user's country

UserResponse

The UserResponse model contains information about a user and their point sets.

Property Type Description
id int Unique identifier for the user
firstName string First name of the user
lastName string Last name of the user
email string Email address of the user
username string Username of the user
dateJoined DateTime Date and time when the user joined
isActive boolean Whether the user is active
avatar string URL to the user's avatar
gender string Gender of the user
birthYear int? Birth year of the user
countryId long? ID of the user's country
partnerId long ID of the user's partner
level string Level of the user
pointSets List List of point sets owned by the user
competitionsEntered int Number of competitions entered by the user
leaderBoardsEntered int Number of leaderboards entered by the user
rewardsUnlocked int Number of rewards unlocked by the user
loginUrl string URL for user login
pointsUrl string URL for user points
rewardsUrl string URL for user rewards

UserDefinedLeaderboards

The UserDefinedLeaderboards model contains information about a user and their leaderboards.

Property Type Description
id int Unique identifier for the user
firstName string First name of the user
lastName string Last name of the user
email string Email address of the user
leaderboards List List of leaderboards the user is part of

JWTSettings

The JWTSettings model contains configuration for JWT token generation.

Property Type Description
jwt_Issuer string The issuer of the JWT token
jwt_Key string The key used to sign the JWT token

Terms and Conditions | Privacy Policy | Acceptable Use Policy | Cookie Policy

Clone this wiki locally