API Reference

Using a Company Session

The Gremlin API offers two types of API sessions. There are Team Sessions, which provide authentication for API interactions to a specific team, and Company Sessions which provide authentication for all API interactions.

Unlike Team Sessions, Company Sessions work across all teams within the company, and so you only need a single session to interact with all of your teams using the Gremlin API. If you have users that do not belong to any teams, you must use this company session.

Gremlin recommends always using this Company Session instead of managing multiple Team Sessions

Acquiring a Company Session and Token

Acquiring a company session is similar to acquiring a team session, however an additional query parameter is required in your API call, as shown here.

Query Param Description
getCompanySession A value of true returns a company session, all other values return a team session
curl -X POST --header "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "email=gremlin@gremlin.com" \
    --data-urlencode "password=changeit" \
    "https://api.gremlin.com/v1/users/auth?getCompanySession=true"

Unlike the response you get for a team session, where a JSON list of session objects are returned, the above request for a company session returns a single JSON object representing the session.

Refer to the API Reference on authentication for more details on this what this API accepts and returns.

Using a Company Session Token

Because company session tokens are used across all of your teams, you must specify an additional query parameter when invoking any API requests that target one of your teams, as shown here.

Query Param Description
teamId The uuid of the target team
# Add 1 core of CPU load to a random host for 30 seconds
curl --header "Content-Type: application/json" \
    --header "Authorization: $company_session_token" \
    "https://api.gremlin.com/v1/attacks/new?teamId=e7352a6b-a9a0-513c-81e4-980f680a70c" \
    --data '
    {
        "command": { "type": "cpu", "args": ["-c", "1", "--length", "30"] },
        "target": { "type": "Random" }
    }'

Refer to the API Reference which outlines which requests require this teamId parameter.