Authentication
Cradl requires you to authenticate using the OAuth2 protocol. Our CLI and SDKs will handle authentication automatically, but if you wish to use the REST API directly, you will need to authenticate manually.
Credentials
You should acquire a client id and client secret by creating an App client in the Cradl UI before continuing. The client id and client secret are used to acquire access tokens for authorizing usage of Cradl.
The endpoint for authentication is https://auth.lucidtech.ai and the endpoint for the API is https://api.lucidtech.ai/v1.
Using the CLI or SDKs
Our CLI and SDKs will handle access tokens for us. The only thing we need to do is to put the credentials in a file as specified below, and our SDKs will use them automatically. Alternatively, you may use environment variables.
The credentials file
The credentials file should be placed in the following location, depending on the OS:
| OS | Location |
|---|---|
| Linux/macOS | ~/.lucidtech/credentials.cfg or $HOME/.lucidtech/credentials.cfg |
| Windows | %USERPROFILE%\.lucidtech\credentials.cfg or %HOME%\.lucidtech\credentials.cfg |
The credentials.cfg file should look like the following:
[default]
client_id = <your client id here>
client_secret = <your client secret here>
auth_endpoint = auth.lucidtech.ai
api_endpoint = https://api.lucidtech.ai/v1
Only the api endpoint should have protocol (https) defined.
Environment variables
export LAS_CLIENT_ID="<your client id here>"
export LAS_CLIENT_SECRET="<your client secret here>"
export LAS_AUTH_ENDPOINT="auth.lucidtech.ai"
export LAS_API_ENDPOINT="https://api.lucidtech.ai/v1"
With the credentials in order you are ready to get started with the CLI or any of the SDKs
Getting an access token manually
To acquire an access token, we query the auth endpoint for access using our client id and client secret. This is done by performing an HTTP POST request to the token endpoint /oauth2/token with two headers provided. One header is 'Authorization' with base64 encoded client_id and client secret and one header is 'Content-Type' which will always contain the same value: application/x-www-form-urlencoded.
| Header name | Header value |
|---|---|
| Authorization | Basic Base64Encode(client_id:client_secret) |
| Content-Type | application/x-www-form-urlencoded |
Read more about Base64Encode here.
Since we are dealing with client_credentials we need to specify this in the URL as a query parameter. The final URL to make the request to is https://auth.lucidtech.ai/oauth2/token?grant_type=client_credentials
Below is an example of getting an access token using cURL in bash.
credentials="<your client id here>:<your client secret here>"
base64_encoded_credentials=`echo -n $credentials | base64 -w 0`
curl -X POST https://auth.lucidtech.ai/oauth2/token?grant_type=client_credentials -H "Content-Type: application/x-www-form-urlencoded" -H "Authorization: Basic $base64_encoded_credentials"
If everything is working as expected, the response should look similar to the following:
{
"access_token": "eyJ...",
"expires_in": 3600,
"token_type": "Bearer"
}
The access token will expire after some time, currently after one hour (3600 seconds ). When the token expires, you need to get a new access token using the same procedure.
Calling the API
After successfully acquiring an access token from the previous step, we are ready to call the API. To do so we need to provide an 'Authorization' header with the newly acquired access token.
| Header name | Header value |
|---|---|
| Authorization | Bearer <your access token here> |
access_token="<you access token here>"
curl https://api.lucidtech.ai/v1/documents -H "Authorization: Bearer $access_token"
Postman
