API Authentication

API Authentication

There are two methods that LegalServer APIs can use to authenticate users for API calls. Basic Authentication which uses a username and password, and Bearer Token Authentication. Currently, there are no differences in functionality between the authentication methods.

In either case, you need to start with a user in LegalServer.

When you read through the User Role Permissions, there are a number that clearly apply to APIs. Grant permission for any that may apply for your use. In addition, you will need to grant the Login permission. If the API is returning a message indicating that the authentication is invalid, it may also be that some non-API related permissions are missing. For example, if you want to use the Reports API to get data on timekeeping, you'll also need to include the permission to see time entries.

You may need to create multiple API Users with different permissions for different projects over time.

Bearer Token Authentication

Bearer token authentication requires a user to create an individualized token and then use that as a proxy for their user account (with the same permissions and access). To create a Personal Access Token, use the Manage Personal Access Tokens block on a User Auxiliary process.

The tokens generated will last for a year or otherwise depending on when they were created. Their access via API will exist expiration or until manually expired. This access will be allowed even if the underlying user is marked as Current = No  or Login = No .

Token Example

With a token of NmUzZDZhNj5465487My00YTUxLWIwZGYtNDE3Z777887878  , the following examples would work to use the Create Matter:

python 
import requests
import json
url = "https://demo4-demo.legalserver.org/api/v1/matters"
payload = json.dumps({"first":"John", 
    "last": "Doe", 
    "case_disposition": "Incomplete Intake", 
    "case_type": "Online Intake" 
})
headers = { 
    "Content-Type": "application/json", 
    "Authorization": "Bearer NmUzZDZhNj5465487My00YTUxLWIwZGYtNDE3Z777887878" 
} 

try: 
    response = requests.request("POST", url, data=payload, headers=headers)
    print(response.text) 
except requests.exceptions.RequestException: 
    print('HTTP Request failed')

or

curl 
curl -X "POST" "https://demo4-demo.legalserver.org/api/v1/matters" \ 
    -H 'Aurhorization: Bearer NmUzZDZhNj5465487My00YTUxLWIwZGYtNDE3Z777887878' \ 
    -H 'Content-Type: application/json; charset=utf-8' \ 
    -d $'{ 
  "first":"John", 
  "last": "Doe", 
  "case_disposition": "Incomplete Intake", 
  "case_type": "Online Intake" 
}'  

Note that in the examples, the Authorization header says "Bearer" and then a long string of letters and numbers. Those letters and numbers are the token itself. Unlike with Basic Authentication below, there isn't a way to pass it in the URL string or as query parameters. This is a security improvement as both the URL and the query parameters may be stored separately or in plaintext, while headers are not typically stored in that manner.

Basic Authentication

LegalServer APIs also support Basic Authentication. This means passing a username and password. The username and password will match that from a user in your LegalServer instance that has the current ability to login to the site and has the appropriate API permission.

Warning: Username is case sensitive in any API calls.

Basic Authentication Examples

With a username of Username   and a password of Password  , the following examples would work to use the Legacy Create Case Note endpoint (which has been deprecated):

html 
https://Username:Password@demo4-demo.legalserver.org/matter/api/create_case_note/?case_number=14-0000005&note=Here%20is%20a%20case%20note.%0A%0AAnd%20more%20text%20here%20after%20two%20line%20breaks.&type=123&subject=Here%20is%20a%20Note%20Subject  

or

python
import requests
url = "https://demo4-demo.legalserver.org/matter/api/create_case_note/"
querystring = {"case_number":"14-0000005",
    "note":"Here's a case note.\n\nAnd more text here after two line breaks.",
    "type":"123",
    "subject":"Here's a Note Subject"
}
payload = "" 
headers = { 'Accept': "application/json" }
response = requests.request("POST", url, data=payload, auth=('username', 'password'), headers=headers, params=querystring)
print(response.text)

or

curl 
curl --request POST \ 
  --url 'https://demo4-demo.legalserver.org/matter/api/create_case_note/?case_number=14-0000005&note=Here'\''s%20a%20case%20note.%0A%0AAnd%20more%20text%20here%20after%20two%20line%20breaks.&type=123&subject=Here'\''s%20a%20Note%20Subject' \ 
  --header 'Accept: application/json' \ 
  --header 'Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ' \  

Note that in the third examples, the Authorization header says "Basic" and then a long random alphanumeric string of gibberish. VXNlcm5hbWU6UGFzc3dvcmQ   is actually a base64 encoded version of the string Username:Password  .

If the API user's password expires, currently the API response is a 200 message with an HTML based response. It is returning the login page that says your password has expired. This will be replaced with a JSON error message soon.

Single Sign On and API Calls

API calls for the Reports API and the Core APIs do not check on the SSO requirements for authentication. Making such an API call with either Basic or Bearer Authentication will work even if SSO is set to "Enabled and Required".