REST APIs

Usage

1. Grab your API keys. Refer to API Keys for more details.

2. When using the APIs, you need to add the following to the requests:

• Application API key. If you are using Publishable Key, you should add the key in the header x-ingrain-publishable-key. If you are using Secret Key, you should add the key in the header x-ingrain-secret-key. If both are present in the headers, secret key will take precedence.
  danger

  You should never use your secret key from your frontend. Secret keys are only for backend.

• User JWT token. This is the JWT of the your app's user whom you are sending the requests on behalf of. It should be added to the Authorization header as a bearer token, e.g. Authorization: Bearer xxxx.

Write Events

Endpoint

POST https://api-prod.ingrain.dev/api/v1/sdk/app-user-events

Request Body

A JSON containing the following properties:

Properties	Type	Description
actorId	String	ID of the user who performed the action.
actorDisplayName	String	User's name to display in Ingrain's UI components.
actorMetadata	Any | null	Additional metadata for the user. This can be any JSON object. Do not store any sensitive or confidential information here. Fields in this object are also available when defining access control rules.
entityId	String	ID of the entity which the action is performed on.
entityName	String	Unique name of the entity, e.g. "personal-token", "task".
entityDisplayLabel	String	Entity's name to display in Ingrain's UI components, e.g. "Personal Token", "Task".
entityMetadata	Any | null	Additional metadata for the entity. This can be any JSON object. Do not store any sensitive or confidential information here. Fields in this object are also available when defining access control rules.
appUserOrgId	String | null	Use this to store your user's team/org/group ID if your application has such concepts. This is a common use case and hence this field was created as a convenience over storing it in actorMetadata.
entityPropName	String | null	The property of the entity that was changed, e.g. "name", "owner".
action	CREATE | UPDATE | DELETE | VIEW	The action performed.
oldValue	String | null	The old value. Do not store any sensitive or confidential information here. If the updated entity is something confidential, for example an access token, the value should not be sent.
newValue	String | null	The new (updated) value. Do not store any sensitive or confidential information here. If the updated entity is something confidential, for example an access token, the value should not be sent.

warning

Do not store any sensitive or confidential information in any of the fields, including oldValue, newValue, and *metadata fields. All the data are returned by the APIs and Ingrain enriches the UI components by displaying relevant information, which may include sensitive information if present.

Response Body

AppUserEvent type

{
  _id: string;
  createdAt: Date;
  applicationId: string;
  actorId: string;
  actorDisplayName: string;
  actorMetadata: JsonValue | null;
  entityId: string;
  entityName: string;
  entityDisplayLabel: string;
  entityMetadata: JsonValue | null;
  entityPropName: string | null;
  appUserOrgId: string | null;
  action: Action;
  oldValue: string | null;
  newValue: string | null;
}

Read Events

Endpoint

GET https://api-prod.ingrain.dev/api/v1/sdk/app-user-events

Query Parameters

The request takes in the following optional parameters:

Parameter	Type	Description
page	Number	1-indexed page to fetch. Default: 1 (first page).
pageSize	Number	Page size to fetch. Min: 1, Max: 25. Default: 25.
actorId	String	ID of the actor to filter by.
entityId	String	ID of the entity to filter by.

Response Body

AppUserEvent Paginated

{
  metadata: {
    totalCount: number;
    page: number;
    pageSize: number;
    numPages: number;
  };
  data: {
    {
      originalPayload: AppUserEvent;
      displayable: {
        // Action in past-tense.
        action: string;
      };
    }
  }[];
}