Authentication

To complete this tutorial, you’ll need either an active Unearth user account with an email and password, or an Unearth service account with an access key and secret access key. You will use these credentials to authenticate with our service prior to making api requests.

If you can log into Unearth’s OnePlace application, you likely already have access to an Unearth User account. If you plan on writing a script or program, that integrates with Unearth and only you ever run or maintain, it may be acceptable to use your user credentials. You can get started with this for testing, or as long as it is acceptable for actions to be performed by your user.

To get a user account, go to Unearth's login screen and click the Start your trial button.

Typically you’ll find that the script or application you are developing needs to act on behalf of multiple users, or will be maintained in a place where it would be inappropriate to store a particular user’s credentials. In these cases you will want to have Unearth set up a service account.

At the moment service accounts can only be created by our team here at Unearth. To request a service account please complete and submit the following Google Form: https://forms.gle/aEb9ee7bjWCdiyuu6. In the meantime if you would like to use your user credentials to get started with the API we’ll provide instructions for authentication with both.

User Authentication

If you are trying to authenticate as a user, using your email and password, it is as easy as making a single request to our authentication server.

Method: POST
Address: https://auth.unearthlabs.com/authenticate
Content-Type: application/json
Body:

{ "email":"YOUR_EMAIL_ADDRESS", "password": "YOUR_PASSWORD"}

In response you will receive a set of tokens:

{  
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",  
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlJlZnJlc2ggRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.DJ2REc5nRP_pGugENadLxFSoWb2M717D4yZ7oU5OrTY"  
}

Service Authentication

If you are trying to authenticate as a service, use the access key and secret access key provided by Unearth.

Method: POST
Address: https://auth.unearthlabs.com/authenticate
Content-Type: application/json
Body:

{  
    "access_key_id": "YOUR_ACCESS_KEY_ID",  
    "secret_access_key": "YOUR_SECRET_ACCESS_KEY"  
}

In response you will receive a set of tokens:

{  
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",  
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlJlZnJlc2ggRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.DJ2REc5nRP_pGugENadLxFSoWb2M717D4yZ7oU5OrTY"  
}

Understanding your tokens

If you successfully authenticate with our server you will receive two tokens. The first token is an identity token. It is the primary token that you will use in the Authorization header of your api calls. This token tells us who you are and grants you permission to access the API for up to 1 hour after it is issued.

The second token is the refreshToken. The refresh token is valid for 30 days and allows you to retrieve a new set of tokens without re-transmitting your username and password or secret access keys. This token exchange should happen with ample time before your identity token expires to ensure that you don’t experience any disruption in your api calls, but can happen any time within 30 days of when the token was issued.

To exchange your refreshToken, it is as easy as making another request:
Method: GET
Address: https://auth.unearthlabs.com/refresh
Header: Authorization: Bearer {YOUR_REFRESH_TOKEN}

In response you will receive two new tokens:

{  
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",  
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlJlZnJlc2ggRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.DJ2REc5nRP_pGugENadLxFSoWb2M717D4yZ7oU5OrTY"  
}