Developers | User management

What This guide outlines how user accounts can be created and managed ongoing via Go1’s public APIs.
Why Organisations may choose to manage users in this way to avoid manual admin tasks of keeping user data up to date including time-sensitive onboarding of new starters, and inaccurate enrolment reporting due to not having up-to-date team, location and other user-specific details.

How it works

There are 5 key interactions:

Generate client ID and secret from within your portal
Authenticate with Go1 APIs using ‘client_credentials’ method
Create a user using Go1’s create user call
Ideally, store the user Go1 user_id from the response to make future updates easier
Update a user using Go1’s update user call

Preparation

Before getting started with our APIs we need to generate Go1 portal-specific client credentials that you will use to authenticate with Go1’s APIs allowing you to read and write within the confines of your Go1 platform.

To generate these you will need to be an administrator on your Go1 platform.
Once logged in as an admin navigate to Integrations > Developers > and create a new app which will provide you with a client ID and Secret

Your Customer Implementation Manager will need to build in any chosen custom profile fields to your Go1 portal as determined by the L&D lead and CIM. Common fields include department, location, and job role.

Your CIM will need to provide the machine names of these fields to the customer's integration lead

Implementation steps

Step 1. Retrieve a customer access token

Before making any user management calls, you will need to authorise your request with a Go1-provided access_token. This access token can be retrieved using the below authentication call, where you will need to provide your client credentials generated from within your Go1 portal as part of the preparation steps above as well as nominate ‘client_credentials’ as the grant type.

This call will respond with an access token valid for 12hrs, and a new token will need to be generated after expiry. Note, generating a new token will automatically invalidate the previous token if still within the 12-hour period.

curl --location --request POST 'https://auth.go1.com/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "client_id": "<CLIENT_ID>",
    "client_secret": "<CLIENT_SECRET>",
    "grant_type": "client_credentials"
}'

Step 2. Create a customer
Users must be created one at a time ie one call per user created. Go1 requires minimal information to create a user ie email, first name, and last name. Go1 role will default to Learner unless specified. You may choose to include additional profile details for each user, please see Preparation for more details about custom profile fields.

curl --location --request POST 'https://api.go1.com/v2/users' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--form 'email="grim@test.com"' \
--form 'first_name="Trace"' \
--form 'last_name="Grimsby"'

The response is a confirmation of the details you have provided along with the user accounts unique Go1 ID.

Note. The Go1 user ID is required for future updates to the same account, it can be stored on the customers side or can be retrieved when needed using a separate call.

{
    "id": 6078052,
    "email": "grim@test.com",
    "first_name": "Trace",
    "last_name": "Grimsby",
    "created": "2021-05-05T02:53:37+00:00",
    "roles": [
        "Learner"
    ],
    "status": true
}

Step 3. Update a user

Users must be updated one at a time ie one call per user created. Updates could include:

Deactivating a user: send "status": false
Changing a name or a custom profile field: send updated name
Changing Go1 role: send updated role(s)
Changing a users manager: send the Go1 ID(s) of manager(s)

Note. Sending updates to names, custom fields, managers, roles will REPLACE existing values.

You do not need to send all user fields in each call, sending just the fields required to be updated is sufficient for example:

curl --location --request PATCH 'https://api.go1.com/v2/users/<GO1_USER_ID>' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "status": false
}'

The response is a summary of the user's account details which will include the updates you have made.

Step 4. Manage group membership

Adding a user to a Go1 group will automatically assign whatever content has been added to the group to the new member's Go1 profile. This is often used when onboarding a new staff member to automatically assign them onboarding training.

Group IDs can be found in the Go1 portal UI under Administer > Groups. User IDs were either stored from the response at user creation or can be retrieved using the List user call with email as the parameter.

Note. While content can be assigned to a group via the API this is generally done manually by the customer's L&D admin from within the Go1 portal UI and therefore not covered in the guide.

curl --location --request POST 'https://api.go1.com/v2/groups/membership' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "group_id": <GROUP_ID>,
  "user_ids": [
    <GO1_USER_ID>
  ]
}'

Deleting a user from a Go1 group may be required if you are maintaining Go1 groups per region, team or other user segment. As a user moves from one segment to another you will want to delete their current membership and add them to a new group.

curl --location --request POST 'https://api.go1.com/v2/groups/membership/delete' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "group_id": <GROUP_ID>,
  "user_ids": [
    <GO1_USER_ID>
  ]
}'

Learn more

Users API Reference
Postman collection
Speak to your Customer Implementation Manager at Go1 to clarify the best use of Go1’s APIs for you.