Skip to main content

​
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.
Yes, the Opigno-Client-UUID header is required for every API request, 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.
The Authorization header is used for server-to-server authorization, allowing your application to access the API and make GraphQL requests. However, it does not identify or link the request to a specific user.The Opigno-Client-UUID is a unique identifier for the user and is required to display user-related data, track progress, and associate actions with a particular user context.
You must include two headers in every API request:
  • Authorization: Bearer YOUR_ACCESS_TOKEN
    This header contains the access token you received after authenticating. It proves that your application is allowed to use the API.
  • Opigno-Client-UUID: your-user-uuid
    This header tells the system which user the request is about. The UUID is a unique identifier for the user. The system checks if your application is allowed to act on behalf of this user.
The Authorization header shows who you are (your application’s identity), and the Opigno-Client-UUID header shows which user you want to manage or get information about.
  • For authenticated users: Generate a unique UUID and call setUserContext with the scope set to AUTHENTICATED.
  • For anonymous users: Generate a unique UUID for each user and call setUserContext without the scope field. This allows tracking of progress and actions for anonymous users, without exposing PII or requiring authentication.

​
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
​
scope
enum
User’s access scope. Determines available features and permissions. This field is optional. For anonymous users, you may omit this field.
Assign the appropriate scope when creating or updating a user context to control access and features. For anonymous users, omit the scope or leave it empty.
  • Authenticated User
  • Anonymous 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
    }
  }
}

​
Parameters

​
uuid
string
required
Unique identifier for the user. A uuidv4 string is recommended, but any unique string may be used if your project requires a different format.
​
displayName
string
required
Full name or pseudonym to display for the user. Avoid exposing PII if not necessary.
​
isActive
boolean
required
Set to true to activate the user context upon creation.
​
scope
enum
User’s access scope. Optional. Typically set to AUTHENTICATED for registered users. Omit for anonymous users.
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
    }
  }
}
​
uuid
string
required
The unique identifier for the user context. Typically, this is a uuidv4 string, but any unique string can be used to suit your project’s requirements.

​
Response fields

​
displayName
string
required
The user’s display name or pseudonym.
​
id
string
required
Internal user context ID.
​
isActive
boolean
Whether the user context is active.
​
scope
array
List of roles or permissions assigned to the user.
​
uuid
string
required
The unique identifier for the user context. Typically, this is a uuidv4 string, but any unique string can be used to suit your project’s requirements.
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.