When integrating with APIs, it's important to understand the concept of scopes. Scopes determine what data a user can access through an API. In Humaans, scopes are dependent on the user's role and the permissions set up in the system.
To learn more about roles and permissions in Humaans, please visit our API documentation.
Available scopes
View public data (public:read)Allow view access to data that is public to the entire company.
View public and private data (private:read)Allow view access to all data except compensations and documents.
Modify public and private data (private:write)Allow modifying all data except compensations and documents.
View compensations (compensations:read)Allow view access to compensation data.
Modify compensations (compensations:write)Allow modifying compensation data.
View documents (documents:read)Allow view access to personal documents and identity documents.
Modify documents (documents:write)Allow modifying personal documents and identity documents.
Manage webhooks (webhooks:manage)Allow view and modifying access to webhooks.
Understanding Scopes
What information the token has access to also depends on the permissions of the user creating the token. For example, is a member with user permissions only created a token with a private:read scope, it would still only provide information about their own account
Even if a user has permission to view certain data through their role permissions, their access token must have the correct scope to actually access that data. This means that a user may have full permissions in Humaans, but their API access can still be limited if their access token does not have the necessary scope.
For example, let's say an owner has full permissions in Humaans. However, if they create an access token with a public:read scope, their API access will be limited to public data only. This means they will not be able to access any private data, such as employee compensation or documents.
If the owner wants to have access to all data through the API, they would need to provide a token with the private:read scope. This would give them access to all data, except for compensation and documents, which are handled separately.
Conclusion
In summary, scopes play a crucial role in determining API access in Humaans. It's important to understand the different scopes available and how they can limit or grant access to data. By setting the correct scope for an access token, users can ensure they have the necessary permissions to access the data they need through the API.