Custom API Integration

Rill exposes custom APIs you have created under apis folder as HTTP endpoints at https://admin.rilldata.com/v1/orgs/<org-name>/projects/<project-name>/runtime/<path to api file>.

Accessing custom APIs

Custom APIs accepts both POST and GET requests to the API endpoint with a bearer token in the Authorization header. For GET requests parameters can be passed in the url.

curl https://admin.rilldata.com/v1/orgs/<org-name>/projects/<project-name>/runtime/<path to api file>[?query-args] \
-H "Authorization: Bearer <token>"

curl -X POST https://admin.rilldata.com/v1/orgs/<org-name>/projects/<project-name>/runtime/<path to api file>[?query-args] \
-H "Authorization: Bearer <token>"

There are two types of bearer tokens that you can use to access the custom APIs:

1. Service Account Token: You can use a service account token to access the custom APIs. Read more about Service Account Tokens.

   note

   1. Service accounts have full access to all APIs so if there are security policies defined for metrics view being used in metrics_sql API, they will not be enforced.
   2. Also since there is no user context available, this means if the api being called uses {{ .user.<attr> }} in SQL templating, it will fail.

2. User Token: You can use a user token to access the custom API when you want user context and enforce security policies defined for the metrics view being used in the metrics_sql API. To get user token you need to perform a handshake with Rill's credentials API using a service account token. Example:

   curl -X POST https://admin.rilldata.com/v1/organizations/<org-name>/projects/<project-name>/credentials \
   -H "Authorization: Bearer <service-account-token>"
   --data-raw '{
     "user_email":"<user-email>"
   }'

   The API accepts the following parameters:

   Parameter	Description	Required
   user_email	The email of the user for which token is being asked for	No (either this or attributes)
   attributes	Json payload containing user attributes used for enforcing policies. When using this make sure to pass all the attributes used in your security policy like email, domain and admin	No (either this or user_email)
   ttl_seconds	The time to live for the iframe URL	No (Default: 86400)