Authentication

You'll need to authenticate your requests to access any of the endpoints in the Forms Live API. Forms Live uses a third-party authentication method that provides secure access while giving end-users control over which applications can access their account.

Third-party authentication

The Forms Live API uses a third-party authentication method that allows integrators to access the API using a standards-based Authorization header. This header is a combination of your API key and an access token encoded as a base64 string.

How it works

  1. API Key: You receive a unique API key for your organization/product from Forms Live
  2. Access Token: End-users generate access tokens for your application via the Forms Live/Realworks user interface or through the Implicit Grant flow
  3. Authorization Header: You combine the API key and access token to create the Authorization header

Benefits

  • Secure: No need to handle usernames and passwords
  • User Control: End-users can revoke access at any time
  • Persistent: Tokens remain active until removed by the user and are unaffected by password changes
  • Stateless: No need to manage sessions in your application

Before you can start making requests to the API, you will need to obtain an API key. Register at https://developer.reiformslive.com.au/ to request an API Key.

Authorization header

Once you have an API Key and end-user access token, you can construct your Authorization header using the following process:

Step-by-step process

  1. Combine your API key and access token with a colon separator
  2. Encode the combined string using base64 encoding
  3. Add the encoded string to the Authorization header with "Basic " prefix
# Example API key
a9d9b0a7-1365-4781-85b3-0fbb36ecd230

# Example access token  
258170b7-d02b-4f8b-aa41-2976f172fa21

# Combine with colon
a9d9b0a7-1365-4781-85b3-0fbb36ecd230:258170b7-d02b-4f8b-aa41-2976f172fa21

# Convert to base64
YTlkOWIwYItNGY4Yi1hYTQxLTI5NzZmMTcyZmEyMQ==

# Authorization header
Authorization: Basic YTlkOWIwYItNGY4Yi1hYTQxLTI5NzZmMTcyZmEyMQ==

Implicit grant

Implicit Grant allows you to generate and retrieve a third-party token easily and securely, without requiring the end-user to manually generate and provide the token through the Forms Live interface.

Prerequisites

To use Implicit Grant, you'll need to:

  1. Contact Forms Live to provide valid redirect_uri(s) (multiple can be used, wildcard not supported)
  2. Receive your unique client_id from Forms Live

Starting the authorization flow

Direct users to the appropriate authorization endpoint via a web browser:

EnvironmentAuthorization URL
Staginghttps://accounts.staging.reiformslive.com.au/oauth/authorize
Productionhttps://accounts.reiformslive.com.au/oauth/authorize

Required parameters

Include these query parameters in your authorization URL:

  • response_type: Must be token
  • client_id: Your unique client ID provided by Forms Live
  • redirect_uri: Your registered redirect URI
  • state: A variable to reduce CSRF risk on your authorization endpoint
  • only: Array of supported APIs/States (act, nsw, nt, qld, sa, tas, wa, vic)
  • api: Default API/State for your application (e.g., qld)
https://accounts.reiformslive.com.au/oauth/authorize?response_type=token&client_id=b4b2bde8-4f5d-49c4-87a0-2f733248c2a5&state=12345&redirect_uri=https://app.your-domain.com/auth&only=qld,nsw&api=qld

Authorization flow

  1. User Login: User is presented with a login dialog
  2. Authorization: User is asked to authorize your app to create and edit forms
  3. Redirect: If approved, user is redirected to your redirect_uri with hash parameters:
    • access_token: The token to use with your API Key
    • token_type: Always "Basic"
    • api: The API/State/Territory linked to their account
    • state: Your original state variable
    • env: Whether the account is staging or production

Security considerations

Token management

  • Keep API keys private: Never expose your API key in client-side code
  • Secure token storage: Store access tokens securely on your servers
  • Token validation: Always validate tokens before making API requests
  • Environment separation: Use different keys for staging and production

Best practices

  • HTTPS only: All API requests must be made over HTTPS
  • State parameter: Always use the state parameter in Implicit Grant to prevent CSRF attacks
  • Token expiration: Monitor for 401 responses indicating expired or invalid tokens
  • Error handling: Implement proper error handling for authentication failures
Check session information

Was this page helpful?