Hoop.dev API is currently in early access mode.


These are the steps to authenticate a machine. For testing purposes, you can call the API using your own user JWT. The JWT can be found in the ~/.hoop/config directory after logging in with the CLI.

1. Generate a client id and client secret

Go to your Identity Provider and create a new user using the client credentials OAuth grant type.
Those are highly confidential, and if they fall into the wrong hands, they can cause significant damage, such as running commands within your organization.

2. Get an authorization token

The token is issued by the identity provider, and the initial request is made directly to the IDP host.
curl --request POST \ --url https://hoophq.us.auth0.com/oauth/token \ --header 'Content-Type: application/json' \ --data '{ "client_id": "generated in step 1", "client_secret": "generated in step 1", "audience": "https://hoophq.us.auth0.com/api/v2/", "grant_type": "client_credentials" }'
{ "access_token": "eyJhb...czVEV5WSJ9.eyJodHR...", "scope": "read:client_grants", "expires_in": 86400, "token_type": "Bearer" }
The response contains a JWT access_token that is used for subsequent requests.

3. Calling Hoop.dev API

To authenticate, the token must be sent as Bearer xxx in the Authorization header of the request. In this example, the token is used to list connections.
curl --request GET \ --url 'https://app.hoop.dev/api/connections' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer eyJhbG...eyJod....j12DOa...'

Important considerations

  • bot user will be created in your org, and used to perform all activities. ({your-app-name}@{your-org-domain})
  • For analytics purposes, all actions taken with this token will be assigned to the bot user
  • The bot user is subject to access control as any other user (using the groups flag)
  • The m2m credentials in the wrong hands can cause some harm

Powered by Notaku