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

• Authentication
• Endpoints
  • Get User
  • Get User By API Key and Slug
  • Get User By API Key (Raw)
  • Get User By Keys
  • Get User Details
  • Update User
  • Upgrade User
• Models
  • UserUpdateModel
  • UserResponse
  • UserDefinedLeaderboards
  • JWTSettings

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}

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:

• Code: 200 OK
• Content: UserResponse object

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": "[email protected]",
  "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
}

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:

• Code: 200 OK
• Content: UserResponse object

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": "[email protected]",
  "username": "johndoe",
  "dateJoined": "2024-01-15T08:30:00Z",
  "isActive": true,
  "partnerId": 456
}

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:

• Code: 200 OK
• Content: UserResponse object

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": "[email protected]",
  "username": "johndoe",
  "dateJoined": "2024-01-15T08:30:00Z",
  "isActive": true,
  "partnerId": 456
}

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": "[email protected]",
  "leaderboards": [
    {
      "id": 1,
      "name": "Monthly Running Challenge",
      "position": 3,
      "points": 250
    }
  ]
}

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.

Updates a user's information.

URL: /api/Users

Method: PATCH

Auth required: Yes (JWT Bearer)

Request Body:

• UserUpdateModel object

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": "[email protected]",
  "birthYear": 1985,
  "gender": "Male",
  "countryId": 1
}

Example Response:

"User updated successfully"

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

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

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

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

The JWTSettings model contains configuration for JWT token generation.