Authentication, Error Codes, and Versioning

Authentication and Authorization

Your application, workplace client, or website can all use API keys in order to access selected workplace systems through NewCraft’s services.

Similar to other API aggregators, we offer a drop-in authenticator where your users can authorize access to their system by logging in. From there, we create an API key specifically for your app and use it to facilitate a connection with the selected workplace system.

When you sign up to work with NewCraft, we will provide you with a client_id and client_secret. These credentials will be used alongside our SDK (which as a drop-in authenticator is directly embedded) in order to generate access tokens and fetch records from external systems.

You can use this NewCraft.js script to add the authenticator to your app.

Types of API keys

The client_id and the client_secret validate that the user has access to NewCraft’s API application. The rest of the authentication is handled by our embedded authentication app.

Access tokens are what allow you to fetch external data via our API. Each access token provides access to a single connected user account. Access tokens are generated by the authenticator app, and can be validated via an API call. Each access token lasts indefinitely, though you can exchange your access token if the one you have is compromised.

In the event that any of your security credentials become compromised, please contact NewCraft support immediately.

Headers

NewCraft’s authenticator app handles all complexities and does not need to send out headers.

Testing

Requests are segregated using sandbox, development, and production apps. The sandbox, development credentials, and sub-domains can be used for testing without affecting anything in production.

API Status and Error Codes

Every request made via NewCraft’s API will return a response. Most frequently, this response will take the form of the status code 200 and the information located at the endpoint you called on. Should your request instead throw an error, the authenticator interface will display an error message and an error code. At this time, we have no custom error codes you need to worry about; all status codes are industry standard.

Versioning

Our goal is to keep NewCraft’s API backwards compatible as long as possible; you don’t have to worry about any near-term updates breaking existing codes. If, in the future, breaking backwards compatibility becomes unavoidable, we’ll version the latest iteration, you can decide if and when you want to deal with incorporating the changes.

Was this section helpful? Yes No