Authentication

You'll need to authenticate your requests to access most of the queries and mutations in the Elements API. In this guide, we'll look at how authentication works.

Bearer Token Authentication

All API requests must be authenticated with a bearer token. You can get a bearer token by signing in to a valid Elements account with an email address and password. The bearer token is a JSON Web Token (JWT) that you can use to authenticate your requests in an Authorization header in the format Bearer {accessToken}. The bearer token is valid for 24 hours.

mutation SignIn($email:String!, $password:String!) {
  signIn(
    input: {usernameOrEmail: $email, password: $password}
  ) {
    user {
      id
    }
    tokenSet {
      accessToken
      refreshToken
    }
    firms {
      items {
        id
      }
    }
  }
}

The result of the signIn mutation contains an accessToken and a refreshToken inside the tokenSet. The accessToken is a JSON Web Token (JWT) that you can use to authenticate your requests in the Authorization header as noted above. The refreshToken is used to get a new accessToken when the current one expires.

Token Refresh

You can use the refreshTokens mutation as noted below to get a new accessToken when the current one expires. The refreshTokens mutation requires a refreshToken as input and returns a new accessToken and refreshToken in the tokenSet.

mutation RefreshTokens($refreshToken:String!) {
  refreshTokens(input: {
    refreshToken: $refreshToken
  }) {
    tokenSet {
      accessToken
      refreshToken
    }
  }
}