Authentication

Our APIs offers two general authentication schemes, one for server-to-server communication and another using short lived JWTs that is meant for client-side, mobile apps, or other shared contexts.

Testing Authentication

You can test either server-side or client-side authentication is working by making a request to the root path for any of our API services.

For example running curl https://meta-api.ervsoftware.co -H "Authorization: [API_TOKEN]" will return the following JSON response:

{"message":"Oh, Hello","time":"2024-02-22T03:54:51Z"}

Server to server

The most basic mode of authentication when using our APIs is is via a static Authorization header using an “Authentication Token” access token provided by our API manager app.

curl -H "Authorization: [API_TOKEN]" \
  https://meta.ervsoftware.co/unfurl?url=github.com/ervsc

Remember to never commit your authentication secret key to git and instead use environment variables or some other secret manager for your framework.

Client-side with JWT

You can use a JWT type access token for client-side access to our APIs. Our API Manager provides a secret key to generate a JWT. You need to set an expiration for the JWT, but there's no limit on the expiration duration.

You must also include a kid header, set to the UUID of your JWT access token. This header represents the "Key ID" and is used by our API to verify your requests. Failure to include this JWT header will result in 500 server errors with the following response:

{"error":"jwt token is missing 'kid' header parameter"}

You can find your UUID value for the kid on the "Access Token" page of our API manager. Once you have generated a JWT and shared it with some other context, requests to our APIs should include the JWT value as Authorization header using the "Bearer" prefix.

fetch('https://meta-api.ervsoftware.co/unfurl?url=github.com/ervsc', {
  method: 'GET',
  headers: {
    "authorization": "Bearer [JWT_VALUE]",
  }
}).then(r => r.json().then(console.log)).catch(console.log)

Below our some quick code examples for generating JWTs. Remember to never commit your JWT secret key to git and instead use environment variables or some other secret manager for your framework.

import jwt
import datetime

# Define your payload
payload = {
  'exp': datetime.datetime.utcnow() + datetime.timedelta(hours=1), # Set expiration date
}

# Generate JWT
token = jwt.encode(payload, "[JWT_SECRET_KEY]", algorithm='HS256', headers={'kid': "[JWT_KID]"})

print(token)