Skip to main content

User-Level Authentication

The Admin API provides two authentication mechanisms depending on your use case. While admin-level authentication allows you to query data across your entire white label application, user-level authentication allows you to access user-specific data as if you were that individual user.

When to Use User-Level Authentication​

User-level authentication is required for accessing endpoints outside of the /v1.0/admin/ routes. Use this authentication method when you need to:

  • Query a user's report data
  • Access current or historical device readings for a specific user
  • Retrieve alert configurations and alert data for a user's account
  • Perform operations that require user context and permissions
info

The Admin API uses client credentials flow for admin-level access. User-level APIs use the Resource Owner Password Credentials flow for user-specific access.

Prerequisites: Obtaining User-Level API Credentials​

Request Separate Credentials

User-level authentication requires different Client ID and Client Secret credentials than admin-level authentication. These credentials are not available in the myDevices console and must be requested separately.

To obtain user-level API credentials:

  • Contact your support team or account manager
  • Request user-level OAuth2 credentials for your white label application
  • You will receive a separate Client ID and Client Secret for user authentication
caution

The admin credentials shown in the myDevices console cannot be used for user-level authentication. Attempting to use admin credentials with user-level endpoints will result in authentication errors.

Authentication Flow​

User-level authentication uses the OAuth2 Resource Owner Password Credentials flow. This requires the user's email and password along with your user-level API credentials.

Obtaining a User Access Token​

Once you have your user-level credentials, use the following curl command to obtain an access token for a specific user:

curl --request POST \
  --url https://api.mydevices.com/v1.0/oauth/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=password&client_id={YOUR_USER_CLIENT_ID}&client_secret={YOUR_USER_CLIENT_SECRET}&username={USER_EMAIL}&password={USER_PASSWORD}'

Replace the placeholders:

  • {YOUR_USER_CLIENT_ID} - Your user-level Client ID (from support, not console)
  • {YOUR_USER_CLIENT_SECRET} - Your user-level Client Secret (from support, not console)
  • {USER_EMAIL} - The user's email address
  • {USER_PASSWORD} - The user's password

Example Response​

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2...",
  "expires_in": 86400,
  "refresh_expires_in": 172800,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2...",
  "token_type": "bearer",
  "not-before-policy": 0,
  "session_state": "91322891-2662-4b3c-8655-9214a7596e2c",
  "scope": "profile email"
}

The access_token is what you'll use in the Authorization header for subsequent API calls. The token is valid for 86400 seconds (24 hours).

Key Differences: Admin vs User Authentication​

Understanding when to use each authentication type is critical for successful API integration:

AspectAdmin AuthenticationUser Authentication
Grant Typeclient_credentialspassword
ScopeAll users in white label applicationSingle specific user
Use CaseBilling, monitoring, cross-user managementUser-specific operations and data
Endpoints/v1.0/admin/*All other API routes
Auth URLhttps://auth.mydevices.com/auth/realms/{REALM}/protocol/openid-connect/tokenhttps://api.mydevices.com/v1.0/oauth/token
Credentials SourcemyDevices console (Admin API section)Request from support team
Required CredentialsClient ID + Client SecretSeparate Client ID + Client Secret + Username + Password
Token Lifespan24 hours24 hours
caution

Do not attempt to use an admin-level token for user-specific endpoints. The API will reject these requests because user-level routes validate that a user ID is associated with the access token.

Complete Example: Getting Device Readings for a User​

Here's a complete example showing how to authenticate as a user and retrieve their device readings:

Step 1: Obtain User Access Token​

curl --request POST \
  --url https://api.mydevices.com/v1.0/oauth/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=password&client_id=myapp-client&client_secret=abc123secret&username=user@example.com&password=userpass123'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cC...",
  "expires_in": 86400,
  "token_type": "bearer"
}

Step 2: Use Token to Query Device Readings​

curl --request GET \
  --url 'https://api.mydevices.com/v1.0/things/4793db10-cf57-11ed-aaaa-292d59ac7b6c/readings?start_ts=1687643022290&end_ts=1687650221820' \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cC...' \
  --header 'Content-Type: application/json'

Response:

{
  "count_took": 2,
  "took": 70,
  "transfer": 986,
  "readings": [
    {
      "ts": 1687650221820,
      "correlation_id": "24856f3a-404f-4b94-adab-72e8a5fc8db9",
      "sensors": [
        {
          "v": 0,
          "channel": "10"
        },
        {
          "v": -64,
          "channel": "100"
        },
        {
          "v": 100,
          "channel": "5"
        }
      ]
    }
  ]
}

Using Refresh Tokens​

To avoid repeatedly authenticating with username and password, use refresh tokens:

curl --request POST \
  --url https://api.mydevices.com/v1.0/oauth/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=refresh_token&client_id={YOUR_CLIENT_ID}&client_secret={YOUR_CLIENT_SECRET}&refresh_token={REFRESH_TOKEN}'

Refresh tokens are valid for 48 hours (172800 seconds) and can be used to obtain new access tokens without requiring the user's password.

Common User-Level Endpoints​

These endpoints require user-level authentication:

EndpointPurpose
GET /v1.0/things/{thing_id}/readingsGet device readings with timestamp range
GET /v1.0/things/{thing_id}/dataGet device data
GET /v1.0/alertsGet user's alert configurations
GET /v1.0/reportsGet user's reports
POST /v1.0/things/{thing_id}/cmdSend commands to user's devices (when not using admin route)

For a complete list of available endpoints, see the API Reference.

Security Considerations​

When implementing user-level authentication:

  1. Secure Credential Storage - Never store user passwords in plain text. Use secure credential management systems or vaults.

  2. Use Refresh Tokens - Minimize password exposure by using refresh tokens instead of repeatedly authenticating with username/password.

  3. Token Management - Store access tokens securely and clear them when they expire or when users log out.

  4. HTTPS Only - Always use HTTPS for API calls to prevent token interception.

  5. Audit Logging - Log authentication attempts and API usage for security monitoring.

  6. Least Privilege - Only request user-level access when necessary. Use admin-level authentication for cross-user operations.

Troubleshooting​

401 Unauthorized Error​

If you receive a 401 error:

  • Verify the user's email and password are correct
  • Check that your Client ID and Client Secret are valid
  • Ensure you're using the correct authentication URL
  • Confirm the user account is enabled and not locked

403 Forbidden Error​

If you receive a 403 error:

  • Verify the user has permissions to access the requested resource
  • Check that you're using a user-level token (not an admin token) for user-specific endpoints
  • Ensure the user owns the device or resource you're trying to access

Token Expired​

Access tokens expire after 24 hours. When this happens:

  • Use the refresh token to obtain a new access token
  • Or re-authenticate with username and password

Next Steps​