Damoov backend registration skill
Skill Mobile-Telematics/damoov-telematics-skills/skills/backend/damoov-backend-registration-skill
Use when implementing Damoov DeviceToken registration in a backend service. Covers production registration flow, hierarchy resolution from admin JWT, admin auth lifecycle, User JWT issuance, and the security pattern for keeping InstanceKey server-side.From its SKILL.md
npx -y skills add Mobile-Telematics/damoov-telematics-skills --skill damoov-backend-registration-skillAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
7.3 KB, as published. Nobody here has run it
Damoov Backend Registration Skill
Use this skill when writing server-side code that:
- Registers new users with the Damoov platform and receives a DeviceToken
- Resolves the Damoov hierarchy (Company → Application → Instance) from admin credentials
- Issues User JWTs to mobile clients via a backend proxy
Never do this
- Never embed
InstanceKeyin a mobile app binary or return it to a mobile client.InstanceKeyis an instance-level secret — treat it like a database password. - Never return a User JWT to a mobile client without issuing it through a backend endpoint that the client authenticates to first (see "Secure User JWT issuance" below).
- Never call
POST /v1/Auth/Loginmore than 5 times per minute per IP — exceeding this triggers a 1-hour block. Always cache the JWT and use Refresh on 401. On 429: if you have aRefreshToken→ use it; if cold start (no RefreshToken yet) → wait 1 hour or use a different IP. - Never store only
AccessToken— always storeRefreshTokenalongside it (RefreshToken lives 3 months). - Never call
setDeviceToken(...)in mobile SDK code — the current API issetDeviceID/setDeviceId(see../../mobile/references/devicetoken-flow.md).
Core concepts
Company
└── Application (one or more per Company)
└── Instance (one or more per Application)
└── Users (each user registered into one Instance)
- InstanceId + InstanceKey — instance-level registration credentials. Required headers for
POST /v1/Registration/create. - DeviceToken — UUID returned after registration. The primary Damoov user identifier. Also called
UserIdorDeviceId— all three refer to the same value. - Admin JWT — company/app/instance-level JWT obtained via
POST /v1/Auth/Login. Used for management API calls. - User JWT — user-level JWT obtained via
POST /v1/Auth/LoginwithDeviceTokenas login andInstanceKeyas password. Used for User Management API calls on behalf of a specific user.
Step 1 — Get admin JWT
See ../../testing/damoov-integration-testing-skill/references/admin-auth.md for the full
login, cache, and refresh flow including rate-limit rules.
Summary:
curl --request POST \
--url 'https://user.telematicssdk.com/v1/Auth/Login' \
--header 'content-type: application/json' \
--data '{"LoginFields":"{\"email\":\"<admin-email>\"}","Password":"<admin-password>"}'
Cache Result.AccessToken.Token (24h) and Result.RefreshToken (3 months).
On any API 401 → call POST /v1/Auth/RefreshToken, not Login.
Step 2 — Get InstanceId + InstanceKey
Option A — Static (recommended for single-instance production setups)
Copy from Datahub → Control Panel → Hierarchy Management → Instance ⋮ → Copy InstanceId / Copy InstanceKey. Store in environment variables. No API call needed.
Option B — Dynamic (multi-instance routing or agent-driven setup)
Resolve from the admin JWT at runtime. See references/hierarchy.md for the full flow:
# 1. Determine access scope
GET https://portal-apis.telematicssdk.com/auth/permissions
Authorization: Bearer <admin-jwt>
# 2. Based on non-empty array in response, call Accounts API:
# instancesPermissions → GET /v1/Instances/{instanceId} → Result.Id, Result.Key
# appsPermissions → GET /v1/Applications/{appId}?includeInstances=true → Result.Instances[].Id, .Key
# companiesPermissions → GET /v1/companies/{companyId}/applications → then app branch above
Cannot create a Company via API. Companies are created during sign-up on the Damoov platform (web UI). If you need a new Company, register at the Damoov portal —
CompanyIdwill be assigned automatically. Then retrieve it via the Permissions API as described above.
Step 3 — Register a user
curl --request POST \
--url https://user.telematicssdk.com/v1/Registration/create \
--header 'InstanceId: <InstanceId>' \
--header 'InstanceKey: <InstanceKey>' \
--header 'content-type: application/json' \
--data '{
"UserFields": { "ClientId": "<your-internal-user-id>" },
"CustomToken": "<your-internal-uuid-if-applicable>",
"CreateAccessToken": false
}'
CustomToken rule:
- If your internal userId is already a UUID → set
CustomToken = userId. Damoov registers it asDeviceTokenso both IDs match. - Otherwise → omit
CustomToken. Damoov generates a new UUID. Store the returnedResult.DeviceTokenin your DB.
Store: internalUserId → DeviceToken in your users table. The DeviceToken is permanent.
Pass to mobile: Return DeviceToken in your login/session response. The mobile app calls setDeviceID(deviceToken) — see ../../mobile/references/devicetoken-flow.md.
Full schema: ../../testing/damoov-integration-testing-skill/references/registration-api.md.
Secure User JWT issuance
A User JWT is required for user-scoped API calls (User Management, user-context Trips/Indicators).
Security rule: InstanceKey must stay on the backend. Do NOT expose it to mobile clients.
Implement a backend endpoint that:
- Authenticates the client (your own auth — e.g. session cookie, OAuth token).
- Looks up the user's
DeviceTokenfrom your DB. - Calls the Damoov User Login API server-side.
- Returns only the
AccessToken.Token(User JWT) to the client.
# Backend calls this on behalf of the authenticated client:
curl --request POST \
--url https://user.telematicssdk.com/v1/Auth/Login \
--header 'InstanceId: <InstanceId>' \
--header 'content-type: application/json' \
--data '{
"LoginFields": "{\"Devicetoken\":\"<DeviceToken-UUID>\"}",
"Password": "<InstanceKey>"
}'
Response: Result.AccessToken.Token is the User JWT (24h lifetime when issued via Login).
Note: Registration-issued AccessToken (when CreateAccessToken: true) has 432000s lifetime (5 days).
Production flow always uses CreateAccessToken: false — only DeviceToken is stored.
Refresh via POST /v1/Auth/RefreshToken — same endpoint as admin refresh.
Admin JWT lifecycle
App startup → POST /v1/Auth/Login (once)
→ cache Token (24h) + RefreshToken (3 months)
Every API call:
→ use cached Token
→ on 401 → POST /v1/Auth/RefreshToken → update cache
→ after 3 months → POST /v1/Auth/Login again
Rate limit: 5 Login calls / minute / IP — exceeding triggers a 1-hour block. Returns 429.
References
references/hierarchy.md— Accounts API: full hierarchy resolution from admin JWT../../testing/damoov-integration-testing-skill/references/admin-auth.md— admin login, refresh, rate-limit rules../../testing/damoov-integration-testing-skill/references/registration-api.md— Registration API full schema../../mobile/references/devicetoken-flow.md— Mobile SDK DeviceToken handoff../../backend/damoov-user-management-skill/SKILL.md— user find, update, delete (requires admin JWT)