Get started with Cloud API

Note: If you are an existing Caseware Cloud API user and have implemented V1, plan your transition to V2. If you are a new user, be sure to start with V2. All examples are from V2.

Caseware Cloud API provides a set of API operations to automate the management of your practice data, such as clients, users, groups, permissions and more.

The SDK app exemplifies the following:

• Available endpoints and operations on each endpoint

• Input and output parameters for each operation

• Required and response headers

Authentication and authorization

By registering an API client and acquiring an API token, you can send requests to Cloud API endpoints. Caseware Cloud API is structured around REST. Predictable resource-oriented URLs deliver JSON-encoded responses, along with standard HTTP response codes.

Cloud API follows the authentication requirements of the client credentials grant flow of the OAuth 2.0 protocol. This flow is designed for confidential, server-to-server communication with no end-user.

To get started:

1. Obtain a client ID and client secret. See Firm Settings - Integration for more information.

2. Next, use the generated client ID and client secret to obtain an API token on POST /auth/token:

Request

curl --location 'https://{region}.casewarecloud.com/{firm}/ms/caseware-cloud/api/v2/auth/token' \         --header 'accept: application/json' \         --header 'Content-Type: application/json' \         --data '{         "ClientId": "966592b3-8586-4541-9909-f7a901ef0b9a",         "ClientSecret": "sg1eb53tkbn6dez0momdxr0gm87fih1kkoekm40u",         "Language": "en"         }'

Response

Status code: 200 OK

             {             "Token": "YTA1NGNiOTgtOWJjOS02NDg5LWIyYTgtZTZhNDA5MDJiNGQwOjk1Y2U2YmRjLWUzMDktMmMxZS00ZDYyLWY5NWJmZGE4MGY1ZjpiYTk4OTc1YS04Mjc4LTRhZWEtOWVjOC0wMDcyM2FhMjRjNGY="             }

Use the API token as a bearer token in an authorization header to make additional API requests. The API token remains valid for 30 minutes.

Session lifetime

Each Cloud API authentication generates a new session that lives for 30 minutes and that doesn’t invalidate any previous sessions. A client secret reset invalidates all existing sessions of that API client. As a result, a new authorization is required.

Rate limit policy

The rate limit aims to prevent the starvation of Cloud API resources. When an API client makes a request, the availability of resources is temporarily decreased and replenished after a certain delay.

When no resources are available, HTTP status 429 (too many requests) is returned. You can use the ratelimit response header to determine the remaining number of requests, burst capacity, replenishment rate, and the number of requested tokens. The token bucket algorithm regulates incoming requests. Imagine a bucket of tokens. When an API request is made, a token must be taken from the bucket to process the request further. The API request is rejected if no token is available in the bucket. Tokens are automatically added to the bucket at the replenishment rate as API requests consume tokens from the available pool.

Response headers

Note: The values of the rate-limit configuration are likely to change. Do not hard code these values.

View API documentation

Cloud API endpoint and parameters are described in the Caseware Cloud SDK app:

To view API documentation:

1. In your browser, go to this URL:

https://{region}.casewarecloud.com/{firm}/sdk

2. On the left, expand /caseware-cloud
3. Select the version you are using.
4. Use the Search to locate the operation you need:

Query parameters that can be used in the API request are described.

See the format of the request URL by expanding the endpoint signature dropdown:

5. Refer to the response samples to the right for listings and descriptions of the data you can expect in the response.