# Equipment Vendor API (for server-to-server cases)

At EGYM, we believe that fitness is the soul of healthy living. Work together with partners to help us bringing new ways of working out to 
millions of gym members, and new ways of prescribing exercises to hundred of thousands of gym trainers, all around the world.

EGYM provides a Fitness Platform for the Connected Gym so you can help us with the mission to ***make the gym work for everyone***. 
EGYM provides a global account that is not scoped for a specific tenant, brand or gym. The account is called EGYM ID. The EGYM ID allows 
users to use different services of the gym. The EGYM ID is used for the login to EGYM hardware and software products and conneceted equipment.   

EGYM works with the best of breed of the fitness industry. In this documentation, we provide tools and info needed to build a variety of workout 
experiences that integrate directly with the EGYM Ecosystem. We are happy to welcome you as a partner of EGYM.

# Introduction

The EGYM Equipment Vendor API Server is an open Web service specification that defines methods to connect and save measurements between the
Partner's Cloud and the EGYM Cloud Platform.

Use the resources below to create, test, and submit your integration to EGYM.

---

# 📦 Changelog of Documentation

| Version | Changes |
|---------|---------|
| **1.1.1** | 🔐 Introduced **NFC-based login** via Apple/Google Wallet — see [`POST /api/v1/oauth/token`](#tag/OAuth/operation/token) |
| **1.1.0** | ✅ Update of Introduction|

---

# Client Authentication

The Equipment Vendor API Server client authentication is based on the API Key.

Currently, different methods for obtaining the Access Token are made available, one by specifying the EGYM User ID (encrypted or obfuscated) and another one by specifying 
the user RFID.

## 🔄 Typical Integration Flow

To integrate your equipment with the EGYM platform, follow this sequence:

1. **Authenticate via OAuth**  
   The standard and recommended method is using RFID-based login (`RFID`) or NFC wallet-based login (`NFC`).

   > Logins using `ENCRYPTED_USER_ID`, `OBFUSCATED_USER_ID`, or `REFRESH_TOKEN` are only for special use cases and require prior alignment with EGYM.

2. **Retrieve User Details**  
   Use the `/api/v1/gyms/{gymId}/users` endpoint with the token to get enriched user data.

3. **Submit a Measurement**  
   Post workout data (body, cardio, flexibility) to the `/api/v1/measurements/...` endpoint.

> All subsequent requests after login must include the `Authorization: Bearer <accessToken>` header.

```plaintext
[Authenticate (POST /oauth/token)]
              ↓
[Get User Details (GET /gyms/{gymId}/users)]
              ↓
[Submit Measurements (POST /measurements/*)]

```

---

## OAuth Login

The `/api/v1/oauth/token` endpoint supports multiple login methods via the `grantType` field. Select the appropriate grant method and use the corresponding request payload.

### Grant Types and Payload Examples

#### 🏷️ RFID Login (Standard)
```json
{
  "grantType": "RFID",
  "rfid": "AB1020CD",
  "rfidFormat": "MIFARE",
  "machineName": "scale"
}
```

#### 📱 NFC Login (Google Wallet)
```json
{
  "grantType": "NFC",
  "machineName": "scale",
  "gymId": 130,
  "payload": "nfc-token-data-abc123",
  "transponderType": "GOOGLE",
  "issuerId": {
    "collector": "123456789"
  }
}
```

#### 📱 NFC Login (Apple Wallet)
```json
{
  "grantType": "NFC",
  "machineName": "scale",
  "gymId": 130,
  "payload": "nfc-token-data-abc123",
  "transponderType": "APPLE",
  "issuerId": {
    "passTypeId": "example.apple.com"
  }
}
```

#### 🔁 NFC Login (with VTAP Configuration Index)
```json
{
  "grantType": "NFC",
  "machineName": "scale",
  "gymId": 130,
  "payload": "nfc-token-data-abc123",
  "transponderType": "GOOGLE",
  "configurationIndex": {
    "configurationIndex": "2"
  }
}
```

---

#### 🔐 Encrypted User ID (Special Case - Requires Approval)
```json
{
  "grantType": "ENCRYPTED_USER_ID",
  "userId": 4337273027797130000
}
```

#### 🧑 Obfuscated User ID (Special Case - Requires Approval)
```json
{
  "grantType": "OBFUSCATED_USER_ID",
  "obfuscatedUserId": "-1c2yqo37vn9m"
}
```

#### 🔄 Refresh Token (Special Case - Requires Approval)
```json
{
  "grantType": "REFRESH_TOKEN",
  "refreshToken": "sample-refresh-token-123"
}
```

##
---

## 👤 Get User Details



### Endpoint: `/api/v1/gyms/{gymId}/users`
Use the access token from login to fetch user profile data:

Returns:
```json
{
  "equipmentUser": {
    "userId": "-1c2yqo37vn9m",
    "firstName": "Max",
    "lastName": "Mustermann",
    "gender": "MALE",
    "dateOfBirth": "1990-01-01",
    "height": 180,
    "weight": 75,
    "locale": "en_US",
    "trainingGoal": "MUSCLE_GAIN"
  }
}
```

---



## 🏋️ Submit Measurements



### Endpoint: `/api/v1/measurements/body`

```json
{
  "timestamp": 1693474800000,
  "machineName": "smartscale123",
  "gymId": 130,
  "uniqueMeasurementId": "unique-id-xyz",
  "data": {
    "weight": 72.5,
    "bodyFat": 15.3
  }
}
```

- `timestamp`: Milliseconds since epoch
- `uniqueMeasurementId`: Must be unique for deduplication
- `data`: Key-value pairs per registered metric

Similar structure is used for `/measurements/cardio` and `/measurements/flexibility`.



---



## 🔒 Security

All requests must include one of:

- `x-api-key`: For login endpoint
- `Authorization: Bearer <accessToken>`: For all other endpoints

---



## ❓ FAQ

This section addresses common technical integration questions specific to the **Server-to-Server** model.

## 1. Authentication
- Use the **API-Key** provided by EGYM for your integration
- API-Key is issued **per gym location**
- Store securely in your backend; do not expose to client devices

## 2. User Identification
- Your backend is responsible for mapping user IDs between your system and EGYM
- Identification methods can include:
  - RFID/NFC data received from devices
  - Account linking between your user database and EGYM

## 3. Data Flow
- Devices send data to your backend
- Backend sends authenticated API requests to EGYM Cloud
- Supports both **real-time** and **batched** submissions

## 4. Key Endpoints for Server-to-Server Integrations
- Authentication: via API-Key in request headers
- User details: `GET /users`
- Measurements: `POST /measurements/*`

## 5. Error Handling Best Practices
- **401 Unauthorized**: Invalid/missing API-Key
- **403 Forbidden**: Permission issue
- **429 Too Many Requests**: Rate limit exceeded; retry after delay
- Implement retry logic with exponential backoff for transient errors

## 6. Rate Limits
- Standard API limits apply – see API documentation
- Monitor usage to avoid hitting limits during batch processing

## 7. Testing
- Use the **EGYM Sandbox** environment for development
- Test credentials are prodvided by EGYM
- Test authentication, user mapping, data submission, and error handling

## 8. What if I send the same measurement twice?**  
Use a different `uniqueMeasurementId` each time.

## 9.When should I use `issuerId` vs `configurationIndex` in NFC?**  
These are alternatives for identifying the wallet pass source. Provide one depending on the integration project with EGYM. Configuration Index is only supported when using the Dot Origin VTAP readers.
---

Version: 1.1.1

## Servers

Generated server url
```
https://b2b-partner-api.ext-1.test.co.egym.coffee
```

## Security

### user

Type: http
Scheme: bearer
Bearer Format: JWT

### partner

Type: apiKey
In: header
Name: x-api-key

## Download OpenAPI description

[Equipment Vendor API (for server-to-server cases)](https://developer.egym.com/_bundle/equipment/Equipment%20Vendor%20API%20Server_August%202025.yaml)

## OAuth

### Login

 - [POST /api/v1/oauth/token](https://developer.egym.com/equipment/equipment-vendor-api-server_august-2025/oauth/createtoken.md): This endpoint logs in the user and returns the access token

### well-known

 - [GET /api/v1/oauth/.well-known/jwks.json](https://developer.egym.com/equipment/equipment-vendor-api-server_august-2025/oauth/wellknown.md): This endpoint returns a JSON Web Key (JWK) set.

## Body Measurement

### Create Body Measurement

 - [POST /api/v1/measurements/body](https://developer.egym.com/equipment/equipment-vendor-api-server_august-2025/body-measurement/createbodymeasurement.md): This endpoint creates a body measurement for the user. See the Body Measurements document for the list of available measurements that can be transferred to EGYM cloud.

## Cardio Measurement

### Create Cardio Measurement

 - [POST /api/v1/measurements/cardio](https://developer.egym.com/equipment/equipment-vendor-api-server_august-2025/cardio-measurement/createcardiomeasurement.md): This endpoint creates a cardio measurement for the user. See the Cardio Measurements document for the list of available measurements that can be transferred to EGYM cloud.

## Flexibility Measurement

### Create Flexibility Measurement

 - [POST /api/v1/measurements/flexibility](https://developer.egym.com/equipment/equipment-vendor-api-server_august-2025/flexibility-measurement/createflexibilitymeasurement.md): This endpoint creates a flexibility measurement for the user. See the Flexibility Measurements document for the list of available measurements that can be transferred to EGYM cloud.

## User Details

### Get user details

 - [GET /api/v1/gyms/{gymId}/users](https://developer.egym.com/equipment/equipment-vendor-api-server_august-2025/user-details/getuserdetails.md): This endpoint retrieves user details in the defined gym location