API Permissions Documentation
Overview
This document provides a comprehensive list of all API endpoints in the KIP People API (Public) and their required permissions. The API uses IdentityServer V2 for authentication and authorization.
Permission System
When multiple permissions are listed in an array, they represent alternative permissions - the user needs to have at least one of the listed permissions to access the endpoint.
For example:
["KIP.People.Users.Me.Items.Read", "KIP.People.Users.Me.Items.Tickets.Read"]means the user needs either the general read permission OR the specific tickets read permission.
Endpoints by Category
My Items
Endpoints for accessing the current authenticated user's items.
| HTTP Method | Route | Operation | Description | Required Permissions (Any One) |
|---|---|---|---|---|
| GET | /users/me/tickets | getUserTickets | Get the current user's tickets | KIP.People.Users.Me.Items.ReadKIP.People.Users.Me.Items.Tickets.Read |
| GET | /users/me/vouchers | getUserVouchers | Get the current user's vouchers | KIP.People.Users.Me.Items.ReadKIP.People.Users.Me.Items.Vouchers.Read |
| GET | /users/me/loyalty-cards | getUserLoyaltyCards | Get the current user's loyalty cards | KIP.People.Users.Me.Items.ReadKIP.People.Users.Me.Items.LoyaltyCards.Read |
| GET | /users/me/transactions | getUserTransactions | Get the current user's transaction history | KIP.People.Users.Me.Items.ReadKIP.People.Users.Me.Items.Transactions.Read |
| GET | /users/me/support-tickets | getUserSupportTickets | Get the current user's support tickets | KIP.People.Users.Me.Items.ReadKIP.People.Users.Me.Items.SupportTickets.Read |
My User Profile
Endpoints for managing the current authenticated user's profile information.
| HTTP Method | Route | Operation | Description | Required Permissions (Any One) |
|---|---|---|---|---|
| DELETE | /users/me/profile | deleteUser | Delete the current user's profile | KIP.People.Users.Me.Profile.Delete |
| GET | /users/me/profile | getBasicProfile | Get the current user's basic profile information | KIP.People.Users.Me.Profile.ReadKIP.People.Users.Me.Profile.Basic.Read |
| PUT | /users/me/profile | updateBasicProfile | Update the current user's basic profile information | KIP.People.Users.Me.Profile.WriteKIP.People.Users.Me.Profile.Basic.Write |
| GET | /users/me/profile/extended | getExtendedProfile | Get the current user's extended profile information | KIP.People.Users.Me.Profile.ReadKIP.People.Users.Me.Profile.Extended.Read |
| PUT | /users/me/profile/extended | updateExtendedProfile | Update the current user's extended profile information | KIP.People.Users.Me.Profile.WriteKIP.People.Users.Me.Profile.Extended.Write |
| GET | /users/me/profile/preferences | getUserPreferences | Get the current user's preferences | KIP.People.Users.Me.Profile.ReadKIP.People.Users.Me.Profile.Preferences.Read |
| PATCH | /users/me/profile/preferences | updateUserPreferences | Update the current user's preferences | KIP.People.Users.Me.Profile.WriteKIP.People.Users.Me.Profile.Preferences.Write |
| GET | /users/me/profile/addresses/{type} | getUserAddressesByType | Get a user's addresses by type | KIP.People.Users.Me.Profile.ReadKIP.People.Users.Me.Profile.Addresses.Read |
| POST | /users/me/profile/addresses/{type} | addUserAddressesOfType | Add a user's address of type | KIP.People.Users.Me.Profile.WriteKIP.People.Users.Me.Profile.Addresses.Write |
| PUT | /users/me/profile/addresses/{type}/{id} | updateUserAddressesOfType | Update a user's address of type | KIP.People.Users.Me.Profile.WriteKIP.People.Users.Me.Profile.Addresses.Write |
| DELETE | /users/me/profile/addresses/{type}/{id} | removeUserAddressesOfType | Remove a user's address | KIP.People.Users.Me.Profile.WriteKIP.People.Users.Me.Profile.Addresses.Write |
| GET | /users/me/profile/student-information | getUserStudentInformation | Get a user's student information | KIP.People.Users.Me.Profile.ReadKIP.People.Users.Me.Profile.StudentInformation.Read |
| GET | /users/me/profile/student-information/{year} | getUserCurrentStudentInformation | Get a user's student information for a academic specified year | KIP.People.Users.Me.Profile.ReadKIP.People.Users.Me.Profile.StudentInformation.Read |
| POST | /users/me/profile/student-information/{year} | addUserCurrentStudentInformation | Add a user's student information for a specific academic year | KIP.People.Users.Profile.WriteKIP.People.Users.Profile.StudentInformation.Write |
| PUT | /users/me/profile/student-information/{year} | updateUserCurrentStudentInformation | Update a user's student information for a specific academic year | KIP.People.Users.Me.Profile.WriteKIP.People.Users.Me.Profile.StudentInformation.Write |
| PUT | /users/me/profile/membership | updateMembership | Update the current user's membership information | KIP.People.Users.Me.Profile.WriteKIP.People.Users.Me.Profile.Membership.Write |
My Movies
Endpoints for managing the current authenticated user's movie-related data.
| HTTP Method | Route | Operation | Description | Required Permissions (Any One) |
|---|---|---|---|---|
| GET | /users/me/movies/history | getHistory | Get current user's movie history | KIP.People.Users.Me.Movies.ReadKIP.People.Users.Me.Movies.History.Read |
| DELETE | /users/me/movies/history/{movieId} | deleteFromHistory | Remove a movie from the current user's movie history | KIP.People.Users.Me.Movies.WriteKIP.People.Users.Me.Movies.History.Write |
| GET | /users/me/movies/recommendations | getRecommendations | Get current user's movie recommendations | KIP.People.Users.Me.Movies.ReadKIP.People.Users.Me.Movies.Recommendations.Read |
| DELETE | /users/me/movies/recommendations/{recommendationId} | deleteFromRecommendations | Remove a movie from the current user's recommendations | KIP.People.Users.Me.Movies.WriteKIP.People.Users.Me.Movies.Recommendations.Write |
| GET | /users/me/movies/wishlist | getWishlist | Get current user's movie wishlist | KIP.People.Users.Me.Movies.ReadKIP.People.Users.Me.Movies.Wishlist.Read |
| POST | /users/me/movies/wishlist | addToWishlist | Add a movie from the current user's movie wishlist | KIP.People.Users.Me.Movies.WriteKIP.People.Users.Me.Movies.Wishlist.Write |
| DELETE | /users/me/movies/wishlist/{movieId} | deleteFromWishlist | Remove a movie from the current user's movie wishlist | KIP.People.Users.Me.Movies.WriteKIP.People.Users.Me.Movies.Wishlist.Write |
My Exports
Endpoints for exporting the current authenticated user's data.
| HTTP Method | Route | Operation | Description | Required Permissions (Any One) |
|---|---|---|---|---|
| POST | /users/me/exports/data | exportUserData | Create an export job for exporting the current user's data | KIP.People.Users.Me.Exports.ReadKIP.People.Users.Me.Exports.GDPR.Read |
Companies
Endpoints for managing companies.
| HTTP Method | Route | Operation | Description | Required Permissions (Any One) |
|---|---|---|---|---|
| POST | /companies | create | Create a new company | KIP.People.Companies.Write |
| PUT | /companies/{companyId} | update | Update an existing company | KIP.People.Companies.Write |
User Items
Endpoints for accessing a specific user's items (requires user ID).
| HTTP Method | Route | Operation | Description | Required Permissions (Any One) |
|---|---|---|---|---|
| GET | /users/{userId}/tickets | getUserTickets | Get a user's tickets | KIP.People.Users.Items.ReadKIP.People.Users.Items.Tickets.Read |
| GET | /users/{userId}/vouchers | getUserVouchers | Get a user's vouchers | KIP.People.Users.Items.ReadKIP.People.Users.Items.Vouchers.Read |
| GET | /users/{userId}/loyalty-cards | getUserLoyaltyCards | Get a user's loyalty cards | KIP.People.Users.Items.ReadKIP.People.Users.Items.LoyaltyCards.Read |
| GET | /users/{userId}/transactions | getUserTransactions | Get a user's transaction history | KIP.People.Users.Items.ReadKIP.People.Users.Items.Transactions.Read |
| GET | /users/{userId}/support-tickets | getUserSupportTickets | Get a user's support tickets | KIP.People.Users.Items.ReadKIP.People.Users.Items.SupportTickets.Read |
User Profile
Endpoints for managing a specific user's profile information (requires user ID).
| HTTP Method | Route | Operation | Description | Required Permissions (Any One) |
|---|---|---|---|---|
| DELETE | /users/{userId}/profile | deleteUser | Delete a user's profile | KIP.People.Users.Profile.Delete |
| GET | /users/{userId}/profile | getUserProfile | Get a user's basic profile information by user ID | KIP.People.Users.Profile.ReadKIP.People.Users.Profile.Basic.Read |
| PUT | /users/{userId}/profile | updateUserProfile | Update a user's basic profile information | KIP.People.Users.Profile.WriteKIP.People.Users.Profile.Basic.Write |
| GET | /users/{userId}/profile/extended | getUserExtendedProfile | Get a user's extended profile information by user ID | KIP.People.Users.Profile.ReadKIP.People.Users.Profile.Extended.Read |
| PUT | /users/{userId}/profile/extended | updateUserExtendedProfile | Update a user's extended profile information | KIP.People.Users.Profile.WriteKIP.People.Users.Profile.Extended.Write |
| GET | /users/{userId}/profile/preferences | getUserPreferences | Get a user's preferences filtered by type | KIP.People.Users.Profile.ReadKIP.People.Users.Profile.Preferences.Read |
| PATCH | /users/{userId}/profile/preferences | updateUserPreferences | Update a user's preferences filtered by type | KIP.People.Users.Profile.WriteKIP.People.Users.Profile.Preferences.Write |
| GET | /users/{userId}/profile/addresses/{type} | getUserAddressesByType | Get a user's addresses by type | KIP.People.Users.Profile.ReadKIP.People.Users.Profile.Addresses.Read |
| POST | /users/{userId}/profile/addresses/{type} | addUserAddressesByType | Add a user's address of type | KIP.People.Users.Profile.WriteKIP.People.Users.Profile.Addresses.Write |
| PUT | /users/{userId}/profile/addresses/{type}/{id} | updateUserAddressesByType | Update a user's address of type | KIP.People.Users.Profile.WriteKIP.People.Users.Profile.Addresses.Write |
| DELETE | /users/{userId}/profile/addresses/{type}/{id} | removeUserAddressesOfType | Remove a user's address | KIP.People.Users.Profile.WriteKIP.People.Users.Profile.Addresses.Write |
| GET | /users/{userId}/profile/student-information | getUserStudentInformation | Get a user's student information | KIP.People.Users.Profile.ReadKIP.People.Users.Profile.StudentInformation.Read |
| GET | /users/{userId}/profile/student-information/{year} | getUserCurrentStudentInformation | Get a user's student information for a academic specified year | KIP.People.Users.Profile.ReadKIP.People.Users.Profile.StudentInformation.Read |
| POST | /users/{userId}/profile/student-information/{year} | addUserCurrentStudentInformation | Add a user's student information for a specific academic year | KIP.People.Users.Profile.WriteKIP.People.Users.Profile.StudentInformation.Write |
| PUT | /users/{userId}/profile/student-information/{year} | updateUserCurrentStudentInformation | Update a user's student information for a specific academic year | KIP.People.Users.Profile.WriteKIP.People.Users.Profile.StudentInformation.Write |
| PUT | /users/{userId}/profile/membership | updateMembership | Update a user's membership information | KIP.People.Users.Profile.WriteKIP.People.Users.Profile.Membership.Write |
User Movies
Endpoints for managing a specific user's movie-related data (requires user ID).
| HTTP Method | Route | Operation | Description | Required Permissions (Any One) |
|---|---|---|---|---|
| GET | /users/{userId}/movies/history | getUserMovieHistory | Get a user's movie history | KIP.People.Users.Movies.ReadKIP.People.Users.Movies.History.Read |
| DELETE | /users/{userId}/movies/history/{movieId} | deleteFromUserHistory | Remove a movie from a user's movie history | KIP.People.Users.Movies.WriteKIP.People.Users.Movies.History.Write |
| GET | /users/{userId}/movies/recommendations | getUserMovieRecommendations | Get a user's movie recommendations | KIP.People.Users.Movies.ReadKIP.People.Users.Movies.Recommendations.Read |
| DELETE | /users/{userId}/movies/recommendations/{recommendationId} | deleteFromUserRecommendations | Remove a movie from a user's recommendations | KIP.People.Users.Movies.WriteKIP.People.Users.Movies.Recommendations.Write |
| GET | /users/{userId}/movies/wishlist | getUserMovieWishlist | Get a user's movie wishlist | KIP.People.Users.Movies.ReadKIP.People.Users.Movies.Wishlist.Read |
| POST | /users/{userId}/movies/wishlist | addToUserWishlist | Add a movie to a user's movie wishlist | KIP.People.Users.Movies.WriteKIP.People.Users.Movies.Wishlist.Write |
| DELETE | /users/{userId}/movies/wishlist/{movieId} | deleteFromUserWishlist | Remove a movie from a user's movie wishlist | KIP.People.Users.Movies.WriteKIP.People.Users.Movies.Wishlist.Write |
User Exports
Endpoints for exporting a specific user's data (requires user ID).
| HTTP Method | Route | Operation | Description | Required Permissions (Any One) |
|---|---|---|---|---|
| POST | /users/{userId}/exports/data | exportUserData | Create an export job for exporting a user's data | KIP.People.Users.Exports.GDPR.Read |
Note: The UserExports interface also has an interface-level permission KIP.People.Users.Exports.Read, but the specific endpoint overrides this with KIP.People.Users.Exports.GDPR.Read.
Metadata
Endpoints for accessing metadata and reference data.
| HTTP Method | Route | Operation | Description | Required Permissions (Any One) |
|---|---|---|---|---|
| GET | /metadata/users/preference-options/{type} | getPreferenceOptions | Get the preference options filtered on type | KIP.People.Metadata.ReadKIP.People.Metadata.Preferences.Read |
| GET | /metadata/users/school-options | getSchoolOptions | Get the school options | KIP.People.Metadata.ReadKIP.People.Metadata.Schools.Read |
| GET | /metadata/users/study-level-options | getStudyLevelOptions | Get the possible study levels | KIP.People.Metadata.ReadKIP.People.Metadata.StudyLevels.Read |
Permission Patterns
Hierarchical Permission Structure
The permissions follow a hierarchical naming convention:
KIP.People.{Resource}.{Scope}.{Action}[.{SubResource}]
Examples:
KIP.People.Users.Me.Profile.Read- General read permission for current user's profileKIP.People.Users.Me.Profile.Basic.Read- Specific read permission for basic profile dataKIP.People.Users.Profile.Write- General write permission for any user's profile
Permission Alternatives
Many endpoints accept multiple alternative permissions, typically following this pattern:
- General permission: Broader scope (e.g.,
KIP.People.Users.Me.Items.Read) - Specific permission: Narrower scope (e.g.,
KIP.People.Users.Me.Items.Tickets.Read)
This allows for flexible permission management where users can be granted either broad access or fine-grained access to specific resources.
"Me" vs User ID Endpoints
The API provides two sets of similar endpoints:
- "Me" endpoints (
/users/me/*): For the current authenticated user, requiring*.Me.*permissions - User ID endpoints (
/users/{userId}/*): For accessing any user's data, requiring*.Users.*permissions (without "Me")
This separation allows for different permission models for self-service operations versus administrative operations.
Notes
- All endpoints return standard error responses including
UnauthorizedError(401) andForbiddenError(403) when authentication or authorization fails. - The API uses IdentityServer V2 for authentication and authorization.
- Permissions are case-sensitive and must match exactly as specified.
- When multiple permissions are listed for an endpoint, having any one of them grants access.