Provisioning API Documentation

The Provisioning API provides possibilities to create and modify organizations.

Authentication

All provisioning API calls are authenticated with a JWT, which is created analog to section Authentication. iat (Issued At), iss (Issuer) and jti (JWT ID) are required fields for the JWT payload. The token is signed with the provisioning key and passed as Bearer <JWT> in the authorization field of the headers. The x-client-id-field is not needed here, because the provisioning will affect the whole SMASHDOCs installation.

Important

The provisioning key for provisioning call is different from the partner API authentication credentials

Code example: JWT in Python

import jwt
import uuid
import datetime

# provided provisioning_key
provisioning_key = '32284ebdc5b8ea867058155b6ebcd7e0f9b0ed0ce2953b0451d9e6dbc9a68e70'

# user_id which issues the provisioning request
user_id = '5813099d5cb91899eea6da05'

jwt_payload = {
    'iat': int(datetime.datetime.now().timestamp()),
    'iss': user_id,
    'jti': str(uuid.uuid4())
}
token = jwt.encode(payload=jwt_payload, key=provisioning_key, algorithm="HS256")
bearer_token = "Bearer {token}".format(token)
print(bearer_token)

Provisioning options

Create Organization

A new organization can be created via POST /provisioning/organization. The organization is initialised with the default smashdocs branding and without any word templates.

In the json request payload, two parameters can be passed:

  • name is the organization’s name (required).
  • replacement_url is an url which is used to to make documents accessible via the partner system. This url must contain the string {doc_id} (e.g. https://partner_url.com/smashdocs/sessions/{doc_id}) which will be replaced with the SMASHDOCs document id. When this url is opened, the partner system has to check the users rights to that document, open the document via the partner api and redirect the user to the documentAccessUrl via HTTP-302.

The response of the API call contains credentials that are necessary for further calls in the partner API and the organization id.

Add a Word Template (optional)

The API call POST /provisioning/organization/{organization_id}/word/upload gives the possibility to add a word template to the organization. The organization id has to be passed as path parameter. In the Request Payload of type “multipart/form-data”, there are two fields:

  • file contains the Word-template itself as docx-file.
  • data contains a json string with additional fields, which determine title and description of the word template.

The id of the new created word template is returned.

Hint

Please find a code example for multipart/form-data uploads here: api_guide.html#importing-word-documents

Update an existing Word Template (optional)

A word template can be updated via POST /provisioning/organization/{organization_id}/word/{template_id}/upload. This call works similar to the create word template call: Additional is only the path parameter template_id, the rest is the same.

The organization id has to be passed as path parameter. In the Request Payload of type “multipart/form-data”, there are two fields:

  • file contains the Word-template itself as docx-file.
  • data contains a json string with additional fields, which determine title and description of the word template.

The id of the updated word template is returned.

Hint

Please find a code example for multipart/form-data uploads here: api_guide.html#importing-word-documents

Examples

POST /provisioning/organization

REQUEST:

URL: https://partner-api.smashdocs.net/provisioning/organization
METHOD: POST
Headers:
    content-type: application/json
    authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0Nzc2NDI1MzAsImlzcyI6IjU4MTMwOTlkNWNiOTE4OTllZWE2ZGEwNSIsImp0aSI6IjcyZTE1NjU2LWYzZDQtNGZhYS05MWNmLWQ1NWJjZjdjYzhmMCJ9.pDmg-kV-bzgDdDTZL5Kn4CgOgPGYpiTdnd9xfwNvROY

Payload:
    {
        "name": "myorganization",
        "replacement_url": "https://smashdocs.myorganization.com/documents/{doc_id}"
    }
RESPONSE:
    {
        "jwt_auth": {
            "client_secret": "1199a4d4052c23d990a402f44c12a73d7db3f80c213380b3da67501cad64a211",
            "client_id": "2fc28f3bdfa2e041f4674f485cfb0393e194ea9b012c1cdbaf62258ac641c62f"
        },
        "password_auth": {
            "superuser_password": "eG5r^Nf@%G|0e/3*ep3}'|`(@,g{EBtu",
            "superuser_email": "myorganization@smashdocs.net"
        }
        "id": "d39f9433-00b3-424b-b797-3e23c0d44d56"
    }

POST /provisioning/organization/{organization_id}/word/upload

REQUEST:

URL: https://partner-api.smashdocs.net/provisioning/organization/d39f9433-00b3-424b-b797-3e23c0d44d56/word/upload
METHOD: POST
Headers:
    content-type: multipart/form-data
    authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0Nzc2NDI2MzEsImlzcyI6IjU4MTMwOTlkNWNiOTE4OTllZWE2ZGEwNSIsImp0aSI6ImI5ZDVhNjk5LWRkNzEtNGNlNi1iYjQwLTIzYjQ4ZjZjYmQ1ZSJ9.EIV11J1vQ1Cv0jWDbNr6d1N63ZCmvqMpZoPExu_TeI0

Payload:
    "file":
         << DOCX - FILE >>
    "data":
        {
            "title": "standard",
            "description": "this is standard template"
        }
RESPONSE:
    {
        "template_id": "75ab3ebf-ad60-44ec-87bf-1248c9568bf6"
    }

POST /provisioning/organization/{organization_id}/word/{template_id}/upload

REQUEST:

URL: https://partner-api.smashdocs.net/provisioning/organization/d39f9433-00b3-424b-b797-3e23c0d44d56/word/75ab3ebf-ad60-44ec-87bf-1248c9568bf6/upload
METHOD: POST
Headers:
    content-type: multipart/form-data
    authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0Nzc2NDI3NTEsImlzcyI6IjU4MTMwOTlkNWNiOTE4OTllZWE2ZGEwNSIsImp0aSI6IjllZjZjNzQ0LTg1MTEtNGEzZi04YTkzLTE2NDhkMGVlNDgxYiJ9.o5HLHZWhZ8HQ2-PFW7BnraR6CWhuH0WrsdJVPd7ElRY

Payload:
    "file":
         << DOCX - FILE >>
    "data":
        {
            "title": "standard",
            "description": "this is my changed description"
        }
RESPONSE:
    {
        "template_id": "75ab3ebf-ad60-44ec-87bf-1248c9568bf6"
    }