Authentication API

Use the Hyper API to authenticate users in your application.

This guide will show how to use the Hyper API to authenticate users in your application.

๐Ÿ“˜

Prerequisites

  • Create a Hyper account
  • Connect Stripe
  • Generate a Publishable API key here

Whether you're building a native app, Chrome extension, mobile app, or website, you can use the Hyper API to authenticate your members with just two API calls. Here's the general flow:

  1. Before a user can enter your application, you show them a login page and prompt them to enter the key they see in the member portal.
  2. You ping the API to ensure that the license exists and is not already being used on another machine.
  3. If the license exists and is not already bound to another machine, you update the license with the IP address, hardware ID, or other parameter that can be used to identify the current machine.
  4. When a user signs out of your application, you update the license again, removing whatever parameter you added in step 3.

This sounds complex at a high level, but we make it really simple by introducing a concept called metadata. In the Hyper API, the metadata field is present on all resources and can be used to store miscellaneous strings that you can use across your application. In this case, metadata is useful because you can use it to store a hardware ID or other identifying trait which can then be cross-referenced when other users try to sign in with the same license. The only two requests you need to know are GET /v6/licenses/:license and PATCH /v6/licenses/:license/metadata.

Here's a simple function you can use to fetch a license from the Hyper API. If the license exists, it will be returned as a JSON object. If it does not exist, the function will throw the License not found error. Naturally, you should replace this with your own logic as you see fit.

async function retrieveLicense(key) {
  try {
    const license = await fetch(`https://api.hyper.co/v6/licenses/${key}`, {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    }).then(res => res.json());
  } catch {
    throw new Error('License not found')
  }
}
def get_license(license_key):
    headers = {
        'Authorization': f'Bearer {API_KEY}'
    }

    req = requests.get(f'https://api.hyper.co/v6/licenses/{license_key}', headers=headers)
    if req.status_code == 200:
        return req.json()

    return None

In this example, let's say you wanted to bind a license to a hardware ID so that it can't be used on other machines. Your next step is to check whether the license is already bound to another hardware ID. This is as simple as three lines of code:

const license = await retrieveLicense('XXXX-XXXX-XXXX-XXXX');
if (license.metadata.hwid) console.log('License is already in use on another machine')
else console.log('License is good to go!')
license_data = get_license('XXXX-XXXX-XXXX-XXXX')
if license_data:
    if license_data.get('metadata') != {}:
        print('License is already in use on another machine!')
    else:
        print('License is good to go!')
else:
    print('License not found!')

From there, you can use this function to update the license with the current machine's hardware ID, so that it can't be used on other devices:

async function updateLicense(key, hwid) {
  await fetch(`https://api.hyper.co/v6/licenses/${key}/metadata`, {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      metadata: { hwid }
    })
  })
}
def update_license(license_key, hardware_id):
    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }

    payload = {
        'metadata': {
            'hwid': hardware_id
        }
    }

    req = requests.patch(f'https://api.hyper.co/v6/licenses/{license_key}/metadata', headers=headers, json=payload)
    if req.status_code == 200:
        return True

  return None

When the user logs out, the code is just as simple:

async function resetLicense(key) {
  await fetch(`https://api.hyper.co/v6/licenses/${key}/metadata`, {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      metadata: { hwid: null }
    })
  })
}
def reset_license(license_key):
    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }

    payload = {
        'metadata': {
            'hwid': None
        }
    }

    req = requests.patch(f'https://api.hyper.co/v6/licenses/{license_key}/metadata', headers=headers, json=payload)
    if req.status_code == 200:
        return True
  
    return None

๐Ÿšง

License revalidation

We highly recommend against revalidating a user's license on an interval (i.e. once every 30 seconds). Instead, you should revalidate upon certain user events (for a bot, this might mean when the user starts a task, for a Chrome extension this might mean when the user opens the popup). There is always a more concise way of revalidating a user's session than pinging the API on an interval, and if you have a large number of users you will run into rate limits.