​
What is a User Context?

A user context is a record that represents a user’s identity and permissions. It helps the system track what a user is doing, what trainings they have, and what they are allowed to access.

​
Types of User Contexts and When to Create

All API requests must include the Opigno-Client-UUID header, regardless of whether the user is authenticated or anonymous. This ensures that every user interaction—authenticated or anonymous—can be tracked and managed via a unique user context.
  • Authenticated Users:
    • Generate a unique UUID for each user.
    • Call setUserContext with the scope set to AUTHENTICATED.
    • This enables full tracking, personalization, and access control.
  • Anonymous Users:
    • Generate a unique UUID for each anonymous user.
    • Call setUserContext without the scope field.
    • This allows tracking of progress and actions for anonymous users, without exposing PII or requiring authentication.
Refer to the setUserContext mutation examples below for both cases.
Create a user context for any user whose actions or progress you want to track and who is authenticated.

​
Understanding Scopes

Scopes define the level of access and permissions granted to a user context. Common scope values include:
  • AUTHENTICATED: Standard authenticated user
You create a user context for a registered, authenticated user by specifying a unique UUID, display name, and setting the scope to AUTHENTICATED.
mutation setUserContext {
  setUserContext(
    uuid: "3bc5b83f-7d96-4b0c-b1e6-627a01d1ab77",
    displayName: "Andrew M. Pearson",
    isActive: true,
    scope: AUTHENTICATED
  ) {
    errors
    response {
      displayName
      id
      isActive
      scope
      uuid
    }
  }
}

​
Special Case: Anonymous User Contexts for Learning Path

In some scenarios, you may want to create a user context for an anonymous user (e.g., to allow them to take a Learning Path without registration). In this case:
  • Use a unique but non-identifiable uuid (e.g., anon-<random>)
  • Set a generic displayName (e.g., “Anonymous User”)
  • Set isActive: true
  • Omit the scope field
This allows tracking progress for anonymous users without requiring authentication or exposing PII.

​
Creating a User Context

To register a new user context, use the setUserContext GraphQL mutation.
1

Prepare the GraphQL Mutation

Use the following mutation, replacing example values with your user data:
mutation setUserContext {
  setUserContext(
    uuid: "3bc5b83f-7d96-4b0c-b1e6-627a01d1ab77",
    displayName: "Andrew M. Pearson",
    isActive: true,
    scope: AUTHENTICATED
  ) {
    errors
    response {
      displayName
      id
      isActive
      scope
      uuid
    }
  }
}
2

Verify the Response

A successful registration returns the new user’s details. Check for errors in the response.
{
  "data": {
    "setUserContext": {
      "errors": [],
      "response": {
        "displayName": "Andrew M. Pearson",
        "id": "4874",
        "isActive": true,
        "scope": ["AUTHENTICATED"],
        "uuid": "3bc5b83f-7d96-4b0c-b1e6-627a01d1ab77"
      }
    }
  }
}
If the errors array is empty, the user context was created successfully.

​
Updating a User Context and Anonymization

To update an existing user context, use the same setUserContext mutation with the updated fields. For anonymization:
  • Use a pseudonymous value for displayName if you do not want to expose real names.
  • Never use personally identifiable information (PII) if not required.
mutation updateUserContext {
  setUserContext(
    uuid: "3bc5b83f-7d96-4b0c-b1e6-627a01d1ab77",
    displayName: "user_12345",
    isActive: true,
    scope: AUTHENTICATED
  ) {
    errors
    response {
      displayName
      uuid
      isActive
      scope
    }
  }
}
For privacy, generate a pseudonymous string for displayName if you do not want to expose real names.

​
Retrieving a User Context

Use the getUserContext GraphQL query to fetch details about a user context.
1

Construct the GraphQL Query

{
  getUserContext(uuid: "17adb4c1-eb29-44bf-9d9a-5f8d056e58ee") {
    displayName
    id
    isActive
    scope
    uuid
  }
}
2

Review the Response

{
  "data": {
    "getUserContext": {
      "displayName": "John Doe",
      "id": "914",
      "isActive": true,
      "scope": ["AUTHENTICATED"],
      "uuid": "17adb4c1-eb29-44bf-9d9a-5f8d056e58ee"
    }
  }
}

​
Publishing and Unpublishing User Contexts

To publish (activate) or unpublish (deactivate) a user context, set the isActive field using the setUserContext mutation: 
mutation deactivateUserContext {
  setUserContext(
    uuid: "3bc5b83f-7d96-4b0c-b1e6-627a01d1ab77",
    isActive: false
  ) {
    errors
    response {
      uuid
      isActive
    }
  }
}
A user context is published when isActive is true and unpublished when isActive is false.