Server-to-Server API

When the user is not around but you need their profile — for example, your server iterates over its users and pulls in their names and avatars — use the Server-to-Server API. It works not on behalf of the user but on behalf of your application: a token from the client_credentials grant with the users.read scope.

1. Get a Server-to-Server token

POSThttps://id.fidmos.com/oauth/token

Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
scope=users.read

Response:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ0eXAiOiJKV1Qi…",
  "scope": "users.read"
}

From then on, add the Authorization: Bearer <access_token> header to every API request.

2. Look up users

The key is the user’s pairwise sub: 64 hex characters, unique per partner. The same sub that arrived when the user signed in — store that one.

In a batch — POST /api/v1/users

POSThttps://id.fidmos.com/api/v1/users

Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{ "sub": ["742ca3e3b6567052f880bb607d5b997b51be4ab0d70d2d52e55f0d5aac8bc24a", "6dac6a4bc0bea7efc53f751359422fa82ba801a13544f269c7d05c94abd7f6ea"] }

The response is a map “submitted key → short profile”. Keys that are not found are not included in the response; the response keys are exactly the ones you sent:

{
  "data": {
    "742ca3e3b6567052f880bb607d5b997b51be4ab0d70d2d52e55f0d5aac8bc24a": {
      "sub": "742ca3e3b6567052f880bb607d5b997b51be4ab0d70d2d52e55f0d5aac8bc24a",
      "avatar": "https://id.fidmos.com/avatar-blank.png",
      "full_name": "Jane Doe"
    },
    "6dac6a4bc0bea7efc53f751359422fa82ba801a13544f269c7d05c94abd7f6ea": {
      "sub": "6dac6a4bc0bea7efc53f751359422fa82ba801a13544f269c7d05c94abd7f6ea",
      "avatar": "https://id.fidmos.com/avatar-blank.png",
      "full_name": "John Smith"
    }
  }
}

Up to 1000 keys at a time. If none are found, data comes back as an empty list.

A single one — GET /api/v1/users/{key}

GEThttps://id.fidmos.com/api/v1/users/742ca3e3b6567052f880bb607d5b997b51be4ab0d70d2d52e55f0d5aac8bc24a

Authorization: Bearer ACCESS_TOKEN

The single response is wider — with the email and separate first and last name:

{
  "data": {
    "sub": "742ca3e3b6567052f880bb607d5b997b51be4ab0d70d2d52e55f0d5aac8bc24a",
    "email": "user@example.com",
    "name": "Jane",
    "last_name": "Doe",
    "avatar": "https://id.fidmos.com/avatar-blank.png",
    "full_name": "Jane Doe"
  }
}

Note

The key is always the pairwise sub (64 hex characters); it also comes back in the response. avatar is always an absolute URL (use it directly as an img src).

Errors

HTTP	When
401	the token is missing, expired or wrong
403	the token lacks the users.read scope
404	(GET only) the key was not found or does not look like a sub (rejected by the route)
422	(POST only) a key in the batch does not look like a sub

A breakdown of the error shapes is in the error reference.