# Cloudspot API wrapper
Basic wrapper for the Cloudspot License API.
# Use cases
1. Authenticate and authorize users on an external app, linked to Cloudspot License
# Getting started
### Install
Install with pip.
```python
pip install cloudspot-license-api
```
### Import
```python
from cloudspotlicense.api import CloudspotLicense_API
```
# Functionalities
### Setup
When setting up the class, one parameter is expected: the id of the external application as present on the license server.
This is a crucial and important step. This id is used to determine what application is making the request and what permissions are linked to it.
By using a wrong id, your users will be able to authenticate themselves if their credentials are correct but the permissions will not be mapped correctly. This may lead to giving users too much or too little permissions on the external application.
```python
from cloudspotlicense.api import CloudspotLicense_API
api = CloudspotLicense_API('app-id')
```
### Authentication and authorization
After setting up the connection, you can use the ```api``` to send requests to the Cloudspot License.
Users that are trying to log in will give their username and password. Send this username and password to the License server to validate their credentials.
If correct, the License server will return a token and the user's permissions for the external application. If not correct, a ```BadCredentials``` error will be raised.
```python
try:
api.authenticate(username, password)
except BadCredentials as e:
print(e)
```
If a request is succesful, you can retrieve the returned token and permissions by using ```api.token``` and ```api.permissions``` respectively.
The ```api.permissions``` will contain an ```AuthPermissions``` object. This is a list of ```AuthPermission``` objects.
An ```AuthPermission``` object looks like this:
```yaml
[
{
"company_id": "COMPANY_ID_1",
"company_name": "COMPANY_NAME_1",
"permissions": [
"use_app"
]
},
{
"company_id": "COMPANY_ID_2",
"company_name": "COMPANY_NAME_2",
"permissions": [
"use_xxx",
"get_xxx",
"use_app"
]
}
]
```
It contains the permissions for each company the user is part of. The ```use_app``` permission is crucial and is always present. If this permission is not present, a user will not be able to authenticate for this company on the external application. A company that hasn't got the ```use_app``` permission assigned, will not be included in the response.
You can loop over the permissions as follows:
```python
for company_perm in api.permissions.items():
print(company_perm.company_id) # Prints the id of the company
print(company_perm.company_name) # Prints the name of the company
print(company_perm.permissions) # Prints an array of all the permissions (slugs)
for perm in company_perm.permissions:
print('perm: ', perm) # Prints the slug of the permission
```
### Retrieving permissions for a specific company, external application and user
You can retrieve the permissions for an external application for a specific user and company. You can only use this function after succesfully authenticating or supplying a token.
```python
from cloudspotlicense.api import CloudspotLicense_API
# 1: authenticate first
api = CloudspotLicense_API('app-id')
auth = api.authenticate('email@example.com', 'my-pwd')
permissions = api.get_company_permissions('company-id')
print('permissions: ', permissions) # Prints an array of all the permissions (slugs)
# 2: OR supply a token
api = CloudspotLicense_API('app-id')
permissions = api.get_company_permissions('company-id', token='token')
print('permissions: ', permissions) # Prints an array of all the permissions (slugs)
```
### Retrieving user info
By default, an empty ```User``` object will be attached to the ```api```. You can retrieve the object with ```api.user```.
To populate the ```User```, you need to execute the function ```api.get_user()``` first.
The ```User``` object has four attributes: ```first_name```, ```last_name```, ```email``` and ```company```.
If you've already authenticated the user before using the ```api```, you do not need to supply a token to the function.
If you're using a new ```api``` object and want to retrieve the user for a specific token without authenticating first, you can supply the token to the function.
If succesful, the user will be attached to ```api.user``` and overwrite any previous user.
Retrieve user by authenticating first.
```python
api.authenticate(username, password)
api.get_user()
print(user.first_name)
```
Retrieve user by supplying a token. You can catch the error ```NoValidToken``` to handle a token that is not valid.
```python
try:
api.get_user(token)
except NoValidToken as e:
print(e)
print(user.first_name)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/Ecosy-EU/cloudspot-license-api",
"name": "cloudspot-license-api",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "cloudspot",
"author": "Alexander Schillemans",
"author_email": "alexander.schillemans@lhs.global",
"download_url": "https://files.pythonhosted.org/packages/fa/82/6059ecc2232d74116347a0f846d4c4bdcbee554727bff428fc48491a136c/cloudspot-license-api-1.4.3.tar.gz",
"platform": null,
"description": "# Cloudspot API wrapper\r\nBasic wrapper for the Cloudspot License API.\r\n\r\n# Use cases\r\n1. Authenticate and authorize users on an external app, linked to Cloudspot License\r\n\r\n# Getting started\r\n\r\n### Install\r\n\r\nInstall with pip.\r\n\r\n```python\r\npip install cloudspot-license-api\r\n```\r\n\r\n### Import\r\n\r\n```python\r\nfrom cloudspotlicense.api import CloudspotLicense_API\r\n```\r\n\r\n# Functionalities\r\n\r\n### Setup\r\n\r\nWhen setting up the class, one parameter is expected: the id of the external application as present on the license server.\r\nThis is a crucial and important step. This id is used to determine what application is making the request and what permissions are linked to it.\r\nBy using a wrong id, your users will be able to authenticate themselves if their credentials are correct but the permissions will not be mapped correctly. This may lead to giving users too much or too little permissions on the external application.\r\n\r\n```python\r\nfrom cloudspotlicense.api import CloudspotLicense_API\r\napi = CloudspotLicense_API('app-id')\r\n```\r\n\r\n### Authentication and authorization\r\n\r\nAfter setting up the connection, you can use the ```api``` to send requests to the Cloudspot License.\r\nUsers that are trying to log in will give their username and password. Send this username and password to the License server to validate their credentials.\r\nIf correct, the License server will return a token and the user's permissions for the external application. If not correct, a ```BadCredentials``` error will be raised.\r\n\r\n```python\r\ntry:\r\n api.authenticate(username, password)\r\nexcept BadCredentials as e:\r\n print(e)\r\n```\r\n\r\nIf a request is succesful, you can retrieve the returned token and permissions by using ```api.token``` and ```api.permissions``` respectively.\r\n\r\nThe ```api.permissions``` will contain an ```AuthPermissions``` object. This is a list of ```AuthPermission``` objects.\r\nAn ```AuthPermission``` object looks like this:\r\n\r\n```yaml\r\n[\r\n {\r\n \"company_id\": \"COMPANY_ID_1\",\r\n \"company_name\": \"COMPANY_NAME_1\",\r\n \"permissions\": [\r\n \"use_app\"\r\n ]\r\n },\r\n {\r\n \"company_id\": \"COMPANY_ID_2\",\r\n \"company_name\": \"COMPANY_NAME_2\",\r\n \"permissions\": [\r\n \"use_xxx\",\r\n \"get_xxx\",\r\n \"use_app\"\r\n ]\r\n }\r\n]\r\n```\r\n\r\nIt contains the permissions for each company the user is part of. The ```use_app``` permission is crucial and is always present. If this permission is not present, a user will not be able to authenticate for this company on the external application. A company that hasn't got the ```use_app``` permission assigned, will not be included in the response.\r\n\r\nYou can loop over the permissions as follows:\r\n\r\n```python\r\nfor company_perm in api.permissions.items():\r\n print(company_perm.company_id) # Prints the id of the company\r\n print(company_perm.company_name) # Prints the name of the company\r\n print(company_perm.permissions) # Prints an array of all the permissions (slugs)\r\n\r\n for perm in company_perm.permissions:\r\n print('perm: ', perm) # Prints the slug of the permission\r\n```\r\n\r\n### Retrieving permissions for a specific company, external application and user\r\n\r\nYou can retrieve the permissions for an external application for a specific user and company. You can only use this function after succesfully authenticating or supplying a token.\r\n\r\n```python\r\nfrom cloudspotlicense.api import CloudspotLicense_API\r\n\r\n# 1: authenticate first\r\napi = CloudspotLicense_API('app-id')\r\nauth = api.authenticate('email@example.com', 'my-pwd')\r\n\r\npermissions = api.get_company_permissions('company-id')\r\nprint('permissions: ', permissions) # Prints an array of all the permissions (slugs)\r\n\r\n# 2: OR supply a token\r\napi = CloudspotLicense_API('app-id')\r\npermissions = api.get_company_permissions('company-id', token='token')\r\nprint('permissions: ', permissions) # Prints an array of all the permissions (slugs)\r\n```\r\n\r\n### Retrieving user info\r\n\r\nBy default, an empty ```User``` object will be attached to the ```api```. You can retrieve the object with ```api.user```.\r\nTo populate the ```User```, you need to execute the function ```api.get_user()``` first.\r\n\r\nThe ```User``` object has four attributes: ```first_name```, ```last_name```, ```email``` and ```company```.\r\n\r\nIf you've already authenticated the user before using the ```api```, you do not need to supply a token to the function.\r\nIf you're using a new ```api``` object and want to retrieve the user for a specific token without authenticating first, you can supply the token to the function.\r\n\r\nIf succesful, the user will be attached to ```api.user``` and overwrite any previous user.\r\n\r\nRetrieve user by authenticating first.\r\n\r\n```python\r\n\r\napi.authenticate(username, password)\r\napi.get_user()\r\n \r\nprint(user.first_name)\r\n```\r\n\r\nRetrieve user by supplying a token. You can catch the error ```NoValidToken``` to handle a token that is not valid.\r\n\r\n```python\r\n\r\ntry:\r\n api.get_user(token)\r\nexcept NoValidToken as e:\r\n print(e)\r\n \r\nprint(user.first_name)\r\n```\r\n\r\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "Wrapper for the Cloudspot License API endpoints",
"version": "1.4.3",
"project_urls": {
"Download": "https://github.com/Ecosy-EU/cloudspot-license-api/archive/refs/tags/1.4.3.tar.gz",
"Homepage": "https://github.com/Ecosy-EU/cloudspot-license-api"
},
"split_keywords": [
"cloudspot"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fa826059ecc2232d74116347a0f846d4c4bdcbee554727bff428fc48491a136c",
"md5": "a4bdce4f828c7b3b1930176ebbf707cd",
"sha256": "4409144026bebda503d91625efb288bd8ba71784fcdfa8e8398512a05a09ddf1"
},
"downloads": -1,
"filename": "cloudspot-license-api-1.4.3.tar.gz",
"has_sig": false,
"md5_digest": "a4bdce4f828c7b3b1930176ebbf707cd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 20308,
"upload_time": "2023-07-20T09:19:16",
"upload_time_iso_8601": "2023-07-20T09:19:16.497803Z",
"url": "https://files.pythonhosted.org/packages/fa/82/6059ecc2232d74116347a0f846d4c4bdcbee554727bff428fc48491a136c/cloudspot-license-api-1.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-20 09:19:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Ecosy-EU",
"github_project": "cloudspot-license-api",
"github_not_found": true,
"lcname": "cloudspot-license-api"
}
JSON
