REST API

The LoginTC REST API allows you to programmatically manage your organization and supports common administration tasks such as: adding users, issuing and revoking tokens, and managing user domain memberships. The REST API is also used to send and check authentication sessions.

Versioning

While the REST API is stable and rarely changes, changes in the future may be required to add additional features. The REST API resources are versioned to ensure all REST API consumers continue to function after API upgrades. The current API version is 1.1. The requested API version is specified in the Accept HTTP header.

Version Release Date Comments
1.0 April 2013 Initial release.
1.1 February 2015 Added ping, organization and domain API calls.

Security

All LoginTC REST API consumers must use HTTPS. Furthermore, all REST API consumers should check and verify the host's SSL certificate. The official client libraries ensure that the SSL certificates are valid.

Resource Base Path

All API REST resource URLs begin with:

https://cloud.logintc.com/api/

For example, to create a new user, POST to:

https://cloud.logintc.com/api/users

Authentication

Your 64-character Organization API key is used to authenticate your API requests using the standard Authorization HTTP header:

Authorization: LoginTC key="YOUR API KEY"

The 64-character API key is found under the Settings tab in LoginTC Admin.

Content Format

The REST API expects and returns JSON content bodies.

To request responses in JSON format use the Accept HTTP header:

Accept: application/vnd.logintc.v1+json

When you include a content body in the request specify the Content-Type HTTP header:

Content-Type: application/vnd.logintc.v1+json

Error Handling

A non 200-level HTTP response code indicates an error has occurred. The body may contain a list of error codes and human-readable error message indicating possible causes and solutions. Example:

> GET /api/users/invalid HTTP/1.1
> Host: cloud.logintc.com
> Accept: application/vnd.logintc.v1+json
> Authorization: LoginTC key="vZkDw7l6Z3tApwZJXERseKdR0s5RNNqjMxXIwvxpWwJOa9oJXi9b5tdvPyFsqzwJ"
--- 
< HTTP/1.1 404 Not Found
< Server: LoginTC-Admin/1.0.2
< Content-Type: application/vnd.logintc.v1+json
< Content-Length: 137
< {"errors":[{"code":"api.error.notfound.user","message":"The specified user does not exist or you do not have permission to access it."}]}

All 200-level HTTP response codes should be treated as successes.

Complete Example

Sample HTTP request and response for a GET on the user resource:

> GET /api/users/8c184f495a5b7b6e9ed732f2ce3c67e310806f38 HTTP/1.1
> Host: cloud.logintc.com
> Accept: application/vnd.logintc.v1+json
> Authorization: LoginTC key="vZkDw7l6Z3tApwZJXERseKdR0s5RNNqjMxXIwvxpWwJOa9oJXi9b5tdvPyFsqzwJ"
---
< HTTP/1.1 200 OK
< Server: LoginTC-Admin/1.0.2
< Content-Type: application/vnd.logintc.v1+json
< Content-Length: 175
< 
< {"id":"8c184f495a5b7b6e9ed732f2ce3c67e310806f38","username":"john.doe","name":"John Doe","email":"john.doe@example.com","domains":["97d28a881da3acdb9895dccd2fe6ec8f865f6df0"]}