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.

pip install cloudspot-license-api

Import

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.

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.

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:

[
  {
        "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:

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.

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.

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.

try:
    api.get_user(token)
except NoValidToken as e:
    print(e)
    
print(user.first_name)