General API Usage

Set up a Tunnel

With version 1.0.16, the groupios HTTP API is now locally accessible on port 8000. This allows for the execution of scripts interacting with groupios either directly on the machine or through the creation of an SSH tunnel with port forwarding.

The provided SSH configuration facilitates access to the API on Port 8001 on your local machine.

Host groupios_server
    hostname <yourip>
    User groupios
    LocalForward 8001 localhost:8000

Note

If connection issues occur, use the loopback IP in your SSH configuration instead: LocalForward 8001 127.0.0.1:8000.

Swagger Documentation

After establishing the SSH tunnel, please access the Swagger documentation. Open your web browser and navigate to localhost:8001 on your machine, assuming you have forwarded to Port 8001. welcome_screen

Click on the writing to open the swagger documentation.

welcome_screen

Note

With groupios 1.0.100, API calls can be executed directly through the Swagger documentation.
Use the authorize button on the top left to enable this.

Retrieve an access token

To obtain an access token, utilize the /token endpoint. Below is an example curl request for the username j.doe@example.com and the password 123456:

curl -X 'POST' \
  'http://localhost:8001/token' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=j.doe%40example.com&password=123456'

Note

Remember to urlencode the request body.

Upon retrieval, you will obtain an access_token object containing an attribute named access_token. This inner access_token string is the value required for subsequent requests.

You can utilize jq to extract the access_token from the result object.

curl -X 'POST' \
  'http://localhost:8001/token' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=j.doe%40example.com&password=123456' | jq -r '.access_token.access_token'

This retrieved access token needs to be present in subsequent API calls.

The token must be included in the Authorization header. For curl, this means you need to add the following parameter in every call: -H 'Authorization: Bearer <your_retrieved_access_token>'