[LA-25920] update docs wrt scopes

source/includes/_activities.md

@@ -57,6 +57,9 @@ View all activity
 
 `GET https://{API_BASE_URL}/v1/activities`
 
+### Required Scope
+This endpoint requires the `activities:read` scope.
+
 Response will be paginated [see pagination](#pagination)
 
 

source/includes/_authentication.md

@@ -69,4 +69,83 @@ Subsequent API calls then require this access token to be present in an **Author
 
 <aside class="success">
 A successful response will return an <code>access_token</code>, please replace <code>YOUR-ACCESS-TOKEN</code> with this value in all authorization headers.
-</aside>
+</aside>
+
+## OAuth Scopes
+
+The Learn Amp API uses OAuth 2.0 scopes to control access to different parts of the API. When requesting an access token, you can specify which scopes you need access to.
+
+By default, tokens are issued with the `public` scope, which provides basic access. For more specific operations, you should request additional scopes.
+
+Legacy scopes are created with full access, and implicitly request and are granted the `public` scope. Moving forward, API credentials should be provisioned with the specific scopes they require.
+
+### Available Scopes
+
+Scope | Description
+--------- | -----------
+public | Basic access scope - included by default
+items:read | Read access to items
+items:create | Create new items
+items:update | Update existing items
+items:delete | Delete items
+items:complete | Mark items as complete
+activities:read | Read access to activities
+enrollments:read | Read access to enrollments
+enrollments:create | Create new enrollments
+events:read | Read access to events
+teams:read | Read access to teams
+teams:create | Create new teams
+teams:update | Update existing teams
+teams:delete | Delete teams
+team_users:read | Read access to team users
+team_users:create | Add users to teams
+team_users:delete | Remove users from teams
+users:read | Read access to users
+users:create | Create new users
+users:update | Update existing users
+users:delete | Delete users
+users:deactivate | Deactivate users
+users:reactivate | Reactivate users
+communities:read | Read access to communities
+tasks:read | Read access to tasks
+verbs:read | Read access to verbs
+languages:read | Read access to languages
+learnlists:read | Read access to learnlists
+channels:read | Read access to channels
+channel_users_progress:read | Read access to channel users progress
+user_channels_progress:read | Read access to user channels progress
+roles:read | Read access to roles
+
+### Requesting Scopes
+
+To request specific scopes, add the `scope` parameter to your token request:
+
+```shell
+curl --location --request POST 'https://api.learnamp.com/oauth/token' \
+--form 'client_id=YOUR-CLIENT-ID' \
+--form 'client_secret=YOUR-CLIENT-SECRET' \
+--form 'grant_type=client_credentials' \
+--form 'scope=items:read items:create'
+```
+
+```ruby
+module Learnamp
+  class Auth
+    include HTTParty
+    base_uri ENV['BASE_URL']
+
+    def self.access_token
+      post('/oauth/token',
+           body: {
+             grant_type: 'client_credentials',
+             client_id: ENV['CLIENT_ID'],
+             client_secret: ENV['CLIENT_SECRET'],
+             scope: 'items:read items:create'
+           })
+    end
+  end
+end
+
+response = Learnamp::Auth.access_token
+puts response["access_token"] if response.ok?
+```

source/includes/_channels.md

@@ -50,6 +50,9 @@ View all channels
 
 `GET https://{API_BASE_URL}/v1/channels`
 
+### Required Scope
+This endpoint requires the `channels:read` scope.
+
 Response will be paginated [see pagination](#pagination)
 
 > 200 OK - successful response:
@@ -109,6 +112,9 @@ View progress of all assigned users through a specified channel. This is analogo
 
 `GET https://{API_BASE_URL}/v1/channels/{channelId}/users_progress`
 
+### Required Scope
+This endpoint requires the `channel_users_progress:read` scope.
+
 This end-point will return a paginated array of users who are assigned the specified channel. Each element will contain the completion percentage of the channel by that user, as well as the datetime (if any) when the channel was completed.
 
 Please note: Only assigned users will be returned. Users who are not assigned the specified channel will not appear in the array.

source/includes/_communities.md

@@ -47,6 +47,9 @@ View all community posts
 
 `GET https://{API_BASE_URL}/v1/communities/:id/posts`
 
+### Required Scope
+This endpoint requires the `communities_posts:read` scope.
+
 Response will be paginated [see pagination](#pagination)
 
 

source/includes/_enrollments.md

@@ -53,6 +53,9 @@ View all events
 
 `GET https://{API_BASE_URL}/v1/enrollments`
 
+### Required Scope
+This endpoint requires the `enrollments:read` scope.
+
 Response will be paginated [see pagination](#pagination)
 
 
@@ -191,8 +194,10 @@ event = Learnamp::Events.new(token).find(1)
 
 Display user details for one specific event.
 
-`GET https://{API_BASE_URL}/v1/event/{eventId}`
+`GET https://{API_BASE_URL}/v1/events/{eventId}`
 
+### Required Scope
+This endpoint requires the `events:read` scope.
 
 > 200 OK - successful response:
 
@@ -267,16 +272,16 @@ Display user details for one specific event.
 
 ## Show an Enrollment
 
-> Display details for a single enrollment:
+> Show a specific enrollment:
 
 ```shell
-curl --location --request GET 'https://api.learnamp.com/v1/enrollments/1' \
+curl --location --request GET 'https://api.learnamp.com/v1/enrollments/52' \
 --header 'Authorization: Bearer YOUR-ACCESS-TOKEN'
 ```
 
 ```ruby
 module Learnamp
-  class Users
+  class Enrollments
     include HTTParty
     base_uri "#{ENV['BASE_URL']}#{ENV['API_PATH']}"
 
@@ -288,7 +293,7 @@ module Learnamp
 
     def find(id)
       response = self.class.get("/enrollments/#{id}", { headers: headers })
-      response.parsed_response if response.ok?
+      response.parsed_response
     end
 
     private
@@ -301,13 +306,15 @@ module Learnamp
   end
 end
 
-enrollment = Learnamp::Enrollments.new(token).find(1)
+enrollment = Learnamp::Enrollments.new(token).find(52)
 ```
 
-Display user details for one specific user.
+Shows details of an enrollment.
 
-`GET https://{API_BASE_URL}/v1/enrollments/{enrollmentId}`
+`GET https://{API_BASE_URL}/v1/enrollments/{id}`
 
+### Required Scope
+This endpoint requires the `enrollments:read` scope.
 
 > 200 OK - successful response:
 
@@ -382,4 +389,63 @@ Display user details for one specific user.
 {
     "error": "Not found"
 }
-```
+```
+
+## Create an Enrollment
+
+> Create a new enrollment:
+
+```shell
+curl --location --request POST 'https://api.learnamp.com/v1/enrollments' \
+--header 'Authorization: Bearer YOUR-ACCESS-TOKEN' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+  "user_id": 1,
+  "event_name": "Leadership workshop",
+  "event_session_id": 5
+}'
+```
+
+```ruby
+module Learnamp
+  class Enrollments
+    include HTTParty
+    base_uri "#{ENV['BASE_URL']}#{ENV['API_PATH']}"
+
+    attr_accessor :token
+
+    def initialize(token)
+      @token = token
+    end
+
+    def create(params)
+      response = self.class.post("/enrollments", { body: params, headers: headers })
+      response.parsed_response
+    end
+
+    private
+
+    def headers
+      {
+        'Authorization' => "Bearer #{token}",
+        'Content-Type' => 'application/json'
+      }
+    end
+  end
+end
+
+params = {
+  user_id: 1,
+  event_name: "Leadership workshop",
+  event_session_id: 5
+}
+
+enrollments = Learnamp::Enrollments.new(token).create(params)
+```
+
+Creates a new enrollment. This will enrol a given user into an event session. By default, the new enrollment will have a status of 'approved'.
+
+`POST https://{API_BASE_URL}/v1/enrollments`
+
+### Required Scope
+This endpoint requires the `enrollments:create` scope.

source/includes/_events.md

@@ -57,6 +57,9 @@ View all events
 
 `GET https://{API_BASE_URL}/v1/events`
 
+### Required Scope
+This endpoint requires the `events:read` scope.
+
 Response will be paginated [see pagination](#pagination)
 
 
@@ -151,6 +154,8 @@ Display user details for one specific event.
 
 `GET https://{API_BASE_URL}/v1/events/{eventId}`
 
+### Required Scope
+This endpoint requires the `events:read` scope.
 
 > 200 OK - successful response:
 

source/includes/_items.md

@@ -47,6 +47,9 @@ View all items
 
 `GET https://{API_BASE_URL}/v1/items`
 
+### Required Scope
+This endpoint requires the `items:read` scope.
+
 Response will be paginated [see pagination](#pagination)
 
 > 200 OK - successful response:
@@ -118,6 +121,8 @@ Display all details for one specific Item.
 
 `GET https://{API_BASE_URL}/v1/items/{itemId}`
 
+### Required Scope
+This endpoint requires the `items:read` scope.
 
 > 200 OK - successful response:
 
@@ -239,6 +244,9 @@ Create an Item
 
 `POST https://{API_BASE_URL}/v1/items`
 
+### Required Scope
+This endpoint requires the `items:create` scope.
+
 ### Data in Body
 
 Parameter (* required) | Example value | Description
@@ -395,6 +403,9 @@ Update an Item
 
 `PUT https://{API_BASE_URL}/v1/items/{itemId}`
 
+### Required Scope
+This endpoint requires the `items:update` scope.
+
 ### Data in Body
 
 Parameter (* required) | Example value | Description
@@ -669,6 +680,8 @@ Delete an Item
 
 `DELETE https://{API_BASE_URL}/v1/items/{itemId}`
 
+### Required Scope
+This endpoint requires the `items:delete` scope.
 
 > 204 No Content - successful response:
 

source/includes/_learnlists.md

@@ -50,6 +50,9 @@ View all learnlists
 
 `GET https://{API_BASE_URL}/v1/learnlists`
 
+### Required Scope
+This endpoint requires the `learnlists:read` scope.
+
 Response will be paginated [see pagination](#pagination)
 
 > 200 OK - successful response:

source/includes/_tasks.md

@@ -74,6 +74,9 @@ View all tasks
 
 `GET https://{API_BASE_URL}/v1/tasks`
 
+### Required Scope
+This endpoint requires the `tasks:read` scope.
+
 Response will be paginated [see pagination](#pagination)