Introduction

Introduction

This is the REST API for LimaCharlie.io. See https://docs.limacharlie.io/docs/api-keys for additional authentication information.

Getting a JWT

Simply issue an HTTP POST such as:

curl -X POST "https://jwt.limacharlie.io" -H "Content-Type: application/x-www-form-urlencoded" -d "oid=<YOUR_OID>&secret=<YOUR_API_KEY>"

where the oid parameter is the organization id as found through the web interface and the secret parameter is the API key.

If you need a JWT that is specific to a single org, you can pass the oid parameter as specified. If you need a JWT that is not specific to a single org, you can pass - as the oid parameter.

The return value is a simple JSON response with a jwt component which is the JSON web token. This token is only valid for one hour to limit the possible damage of a leak, and make the deletion of the API keys easier.

Example Response:

{ "jwt": "<JWT_VALUE_HERE>" }

Additionally, if you need an API key which is scoped to a specific user, include uid=<YOUR_UID> instead of oid parameter and instead of organization API key, you need to use the user scoped API key for the secret parameter.

You can generate a user scoped API key at https://app.limacharlie.io/profile -> User API Keys and obtain your User ID by clicking "User ID" icon on the right top side of the same page.

Example cURL request to obtain JWT token which is scoped to a specific user:

curl -X POST "https://jwt.limacharlie.io" -H "Content-Type: application/x-www-form-urlencoded" -d "uid=<YOUR_UID>&secret=<YOUR_USER_SCOPED_API_KEY>"test

Keep in mind that using organization scoped tokens is preferred. You should only user a user scoped token if there is a specific need for it or you are using an API endpoint which operates on the user behalf and requires user scoped token (e.g. POST /v1/users/invite).

Token Size Considerations

By default, a user scoped token will include permissions for all organizations your user account has access to. If your user belongs to many organizations, the resulting JWT may become very large, potentially exceeding HTTP header size limits and causing issues with some APIs or clients.

To avoid this:

• Prefer organization scoped tokens when possible.

• Alternatively, when requesting a user scoped token, you can explicitly exclude organization permissions by using the ?oid=- parameter as shown below. This works with API endpoints which operate on behalf of the user (e.g. /v1/users/invite).

curl -X POST "https://jwt.limacharlie.io" -H "Content-Type: application/x-www-form-urlencoded" -d "uid=<YOUR_UID>&secret=<YOUR_USER_SCOPED_API_KEY>&oid=-"

Python Example

Organization Scoped API Key

import os
import json
import requests

# Step 1 - Generate a JWT
def generate_jwt():
    oid = os.getenv("LIMACHARLIE_OID", "")
    api_key = os.getenv("LIMACHARLIE_ORG_API_KEY", "")

    url = f"https://jwt.limacharlie.io?oid={oid}&secret={api_key}"

    try:
        r = requests.get(url)
        jwt = r.json()["jwt"]
        return jwt

    except:
        return None

# Step 2 - Make an API request
def create_org(loc, name):
    url = "https://api.limacharlie.io/v1/orgs/new"

    headers = {
        "Content-Type": "application/json",
        "Authorization": "Bearer %s" % (generate_jwt()),
    }
    params = {"loc": loc, "name": name}
    response = requests.request("POST", url, headers=headers, params=params)

    return json.loads(response.text)

User Scoped API Key

import os
import json
import requests

# Step 1 - Generate a JWT
def generate_jwt():
    uid = os.getenv("LIMACHARLIE_UID", "")
    api_key = os.getenv("LIMACHARLIE_USER_API_KEY", "")

    url = f"https://jwt.limacharlie.io?uid={uid}&secret={api_key}"

    try:
        r = requests.get(url)
        jwt = r.json()["jwt"]
        return jwt

    except:
        return None

# Step 2 - Make an API request
def create_org(loc, name):
    url = "https://api.limacharlie.io/v1/orgs/new"

    headers = {
        "Content-Type": "application/json",
        "Authorization": "Bearer %s" % (generate_jwt()),
    }
    params = {"loc": loc, "name": name}
    response = requests.request("POST", url, headers=headers, params=params)

    return json.loads(response.text)

Terms of Service