GraphQL API source configuration reference

When creating a GraphQL API source in the Coveo Administration Console, you must provide a JSON configuration detailing what to crawl to retrieve the desired content, and how to retrieve items of each type. This configuration has a single property, Services, whose value must be an array of objects.

Example
{
  "Services": [
    {
      "Url": "https://api.github.com/",
      "authentication": {
        "username": "@username",
        "password": "@password",
        "forceBasicAuthentication": "true"
      },
      "Endpoints": [
        {
          "paging": {
            "pageSize": 10,
            "offsetType": "cursor",
            "nextPageKey": "data.user.pullRequests.pageInfo.endCursor"
          },
          "headers": {
            "accept": "application/vnd.github.v3+json",
            "User-Agent": "PostmanRuntime/7.29.0"
          },
          "Path": "graphql",
          "Method": "POST",
          "ItemPath": "data.user.pullRequests.edges",
          "SkippableErrorCodes": "404",
          "ItemType": "PullRequests",
          "Uri": "%[node.url]",
          "ClickableUri": "%[node.url]",
          "Title": "%[node.title]",
          "ModifiedDate": "%[node.createdAt]",
          "PayloadJsonContent": "@MyFirstQuery"
        }
      ]
    }
  ]
}

This reference article defines parameters to include in your JSON configuration.

When building your JSON configuration, you may also want to refer to the Concepts article.

About the GraphQL API source configuration

When you create a GraphQL API source in the Coveo Administration Console, you must provide a JSON source configuration listing the content to crawl. This JSON configuration must also indicate which API calls to execute to fetch the desired items and how to parse the responses to extract relevant metadata.

Coveo’s GraphQL API connector is actually the REST API connector under the hood. So, the JSON configuration to provide is very similar. Although the expected configuration follows the repository structure of a REST API, with services and endpoints, it also works with GraphQL APIs.

Table of contents

To help you jump to the right section, here’s a hierarchical and alphabetical list of all supported arrays, objects, and parameters.

Show table of contents
Hierarchical list Alphabetical list

AccessToken

ActionOnItem

AdditionalInfo

AllowedMembers

Authentication

AuthorizationHeader

Body

ClickableUri

Condition (action on item)

Condition (permission)

DateFormat

DeleteChildren

DeniedMembers

Domain

Endpoints

ExpiresIn

ExpiresInDefaultValue

ForceBasicAuthentication

Headers (OAuth query)

Headers (service level)

IndexingAction

IsAllowedMember

IsAnonymousAllowed

IsBinaryBody

IsDeletedItem

IsDeletionQuery

IsThumbnail

ItemPath

ItemType

Metadata

Method (endpoint query)

Method (OAuth query)

ModifiedDate

Name (member)

Name (permission level)

Name (permission set)

NextPageKey

OAuth

OffsetStart

OffsetType

PageSize

Paging

Parameters (OAuth query)

Password

Path

PayloadJsonContent

PayloadParameters

PermanentId

Permissions

PermissionsFromMetadata

PermissionsSets

PermissionSubQueries

PermissionType

ProcessingAction

Query

QueryParameters

RefreshEndpoints

RefreshToken

RefreshUrl

Response

Services

SkippableErrorCodes

StringItemPath

SubItems

SubQueries

SupportsRefreshToken

Title

TokenType

TokenTypeDefaultValue

TotalCountKey

TotalCountHeaderKey

Type (member)

Uri

Url

Username

Services (array, required)

Each object in the Services array specifies a GraphQL API service to retrieve content, along with the specific endpoints to call.

The properties that may appear in an object of the Services array are the following:

Endpoints (array, required)

Services > Endpoints

Each object in the Endpoints array details how you want Coveo to crawl an endpoint of your web application.

Moreover, in each endpoint object, the Metadata objects lists the content metadata to retrieve.

Objects of the Endpoints array support the following properties from their parent service object:

It also supports the following properties:

ClickableUri (string, required)

Services > Endpoints > ClickableUri

The format of the item clickable URI.

Dynamic values are supported.

Example: "ClickableUri": "%[node.url]"

ItemType (string, required)

Services > Endpoints > ItemType

The type of item that the resource contains. Coveo uses this data to organize the indexed content.

Examples:

  • "ItemType": "Post" for a blog post

  • "ItemType": "PostComment" for a comment on a post

Path (string, required)

Services > Endpoints > Path

The relative path to the desired resource endpoint.

Dynamic values are supported when specified within the SubItems, SubQueries, and PermissionSubQueries arrays only.

Dynamic time expressions are also supported.

Example: "Path": "graphql"

In sub-items and subqueries, should a dynamic value be invalid or unretrievable, the source skips the item, that is, the indexing process is dropped and Coveo moves on to the next item. In a permission subquery, however, an invalid or unretrievable dynamic value causes the source to stop crawling and to display an error in the Administration Console.

Uri (string, required)

The format of the item unique identifier.

Dynamic values are supported.

Example: "Uri": "%[node.url]"

Should a dynamic value be invalid or unretrievable, the source stops crawling and displays an error in the Administration Console.

Body (string)

Services > Endpoints > Body

The path (simple path or JSONPath) to the Body content of the item in the JSON response. The item body is displayed in the Content Browser.

Typically, the Body property contains a dynamic value, since a static, hardcoded value would make all item bodies identical. Dynamic values and hardcoded text can also be mixed.

Example: "Body": "%[html.content]"

DateFormat (string)

Services > Endpoints > DateFormat

The format of a date injected thanks to the tokens @Now and @RefreshDate.

All .NET formats are supported, and the default is yyyy-MM-ddTHH:mm:ssZ (ISO 8601).

Alternatively, to handle Unix timestamps, enter either of the following:

  • UnixEpoch for the number of seconds elapsed since the Unix epoch.

  • UnixEpochMs for the number of milliseconds elapsed since the Unix epoch.

Coveo also uses this format when parsing dates coming from your API. If these dates aren’t in a .NET format, use DateFormat to specify the format to expect.

Examples:

  • "DateFormat": "yyyy-MM-ddTHH:mm:ssZ"

  • "DateFormat": "\\'yyyy-MM-dd\\',\\'hh:mm:ss\\'"

IndexingAction (object)

Services > Endpoints > IndexingAction

Whether to ignore or to retrieve an item when a condition is met.

When the Condition resolves to true, the Coveo crawler applies the specified action to the item. Possible actions are Retrieve and Ignore, that is, the crawler can either index the item or ignore it.

An item ignored with IndexingAction isn’t indexed and therefore not visible in the Content Browser or a search interface. However, its sub-items are sent to the index, unless otherwise specified in the ProcessingAction object.

If the condition resolves to false, the Coveo crawler falls back to the default action, which is Retrieve, and the specified item is indexed.

Example:

"IndexingAction": {
    "ActionOnItem": "Ignore",
    "Condition": "%[id] > 1"
}

The IndexingAction object supports the following properties:

ActionOnItem (string, required)

Services > Endpoints > IndexingAction > ActionOnItem

Action to perform if the specified Condition resolves to true.

In the IndexingAction object, this applies to retrieved items. Possible actions are Retrieve and Ignore, that is, the crawler can either index the item to make it searchable or ignore it.

In the ProcessingAction object, this applies to child items of an item. Possible actions are Process and Ignore, that is, the crawler can either retrieve the subitems to make them searchable or ignore them.

Action Condition (string)

The Condition value is a condition that must resolve to true for the specified action to apply to the child items of an item.

To write your condition, use the same syntax as for indexing pipeline extension conditions.

Conditions can be assembled using the following operators: AND, OR, Exists, NOT, ==, >, and <.

Parentheses are also supported to specify operation order.

Important

The > and < operators can only be used with numeric metadata, not with date metadata.

The metadata fields in your condition must either be defined in the Metadata object or referenced with raw. You can specify an array if the metadata refers to a multi-value field in your repository.

Examples:

  • "%[node.author_id]" is true if the item has an author_id.

  • "NOT %[node.author_id]" is true if the item doesn’t have an author_id.

  • "%[node.author_id] == 1234" is true if the item author_id is 1234.

  • "%[node.author_ids] == [1,2,3,4]" is true if item author_ids are 1, 2, 3, and 4.

  • "%[node.author_id] OR %[author_name]" is true if the item has an author_id or an author_name.

  • "%[node.author_id] AND %[author_name]" is true if the item has an author_id and an author_name.

  • "%[node.author_id] > 123" is true if the item author_id is greater than 123.

  • "(%[node.author_id] OR %[node.author_sys_id]) AND %[node.author_name]" is true if the item has an author_id or an author_name, as well as an author_name.

IsBinaryBody (Boolean)

Services > Endpoints > IsBinaryBody

Whether the subquery retrieves binary content as the body of the item. Default value is false.

This property is available within SubQueries objects only. It allows you to download a file (for example, XLS or PDF document) to use as the item body in a search result quick view. See Supported file formats for an exhaustive list of item types that Coveo can index.

Example:

"SubQueries": [
{
  "Path":"%[coveo_parent.url]",
  "Method":"GET",
  "IsBinaryBody":true,
  "Body": "%[data.body]"
}
]
Notes
  • IsBinaryBody and IsThumbnail are mutually exclusive. In other words, if you set IsBinaryBody to true, you must set IsThumbnail to false, and vice versa.

  • If Coveo fails to index the item’s body, ensure that your API key is valid for subqueries, and try adding a Headers object to your subquery.

ItemPath (string)

Services > Endpoints > ItemPath

The path to the item in the JSON response returned by the application.

When ItemPath is omitted, Coveo assumes that the item is at the root level of the JSON response.

Note

ItemPath and StringItemPath are mutually exclusive. In other words, if you use ItemPath in a permission subquery, you can’t also use StringItemPath, and vice versa.

Metadata (object)

Services > Endpoints > Metadata

A key-value list of the metadata to parse.

Each key represents the metadata name of the item, while its value is the value path (simple path or JSONPath) in the JSON response.

Typically, the value path consists of one or more dynamic values, since a static, hardcoded value would result in an identical piece of metadata for all items. However, you could choose to use a hardcoded value so that the corresponding Coveo field is filled even if the API doesn’t provide this information.

Example:

"Metadata": {
  "author": "hardcoded value",
  "id": "%[id]",
  "expiration": "%[info.expiration]",
  "createdby": "Mr. %[author]",
  "authorUrl": "%[coveo_url]/authors/%[id]",
  "description": "%[author] is an amazing author!"
}

When you build your source, Coveo retrieves the desired metadata. You can then review a sample of this metadata in the Administration Console and use it to create mapping rules for your source.

Method (string enum)

Services > Endpoints > Method

The HTTP method to use to fetch the resource.

Possible values are GET and POST. Default value is GET.

This property is not inheritable.

See the API’s documentation to determine which one you should use.

Example: "Method": "POST"

ModifiedDate (string)

Services > Endpoints > ModifiedDate

The date on which the item was last modified. Although this property isn’t required in the JSON configuration, we recommend that you include it, as the Coveo-powered search pages use it for their default Sort by date option.

Typically, ModifiedDate has a dynamic value, since a static, hardcoded value would make dates identical for all items.

Example: "ModifiedDate": "%[updated]"

PayloadJsonContent (string)

Services > Endpoints > PayloadJsonContent

The content to send as a POST request body. This can be either of the following:

  • A placeholder for a GraphQL query that you’ll enter separately, in the GraphQL queries section.

  • An escaped JSON string.

We highly encourage you to use a placeholder, as the escaped JSON is harder to read and edit due to the large number of backslashes.

The Content-Type header is automatically set to application/json.

Dynamic values are supported when specified within the SubItems and SubQueries objects only.

In sub-items and subqueries, should a dynamic value be invalid or unretrievable, the source skips the item, that is, the indexing process is dropped and Coveo moves on to the next item. In a permission subquery, however, an invalid or unretrievable dynamic value causes the source to stop crawling and to display an error in the Administration Console.

Note

PayloadJsonContent and PayloadParameters are mutually exclusive. In other words, if you provide a PayloadJsonContent string, you cannot provide payload parameters, and vice versa.

Example

You want to make the following POST GraphQL query:

query {
  user(login:"jsmith") {
    pullRequests(first:@pageSize, after:@offset) {
      totalCount
      edges {
        node {
          createdAt
          title
          url
        }
        cursor
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

When entering this query in the GraphQL queries section, you name it @MyFirstQuery.

Your source JSON configuration therefore contains the following:

"Endpoints": [
  {
    "Method": "POST",
    "Path": "graphql",
    "PayloadJsonContent": "@MyFirstQuery"
  }
]

Alternatively, you can convert your POST GraphQL query payload to a JSON string with appropriate escaping, and then enter it directly as the PayloadJsonContent value.

For example, if your payload is:

query {
  user(login:"jsmith") {
    pullRequests(first:@pageSize, after:@offset) {
      totalCount
      edges {
        node {
          createdAt
          title
          url
        }
        cursor
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

Then your source configuration should contain:

{
  "Path": "graphql",
  "Method": "POST",
  "ItemType": "PullRequests",
  "Uri": "%[node.url]",
  "ClickableUri": "%[node.url]",
  "Title": "%[node.title]",
  "ModifiedDate": "%[node.createdAt]",
  "PayloadJsonContent": "{\"query\":\"query {\\r\\n user(login:\\\"jsmith\\\") {\\r\\n pullRequests(first:@pageSize, after:@offset) {\\r\\n totalCount\\r\\n edges {\\r\\n node {\\r\\n createdAt\\r\\n title\\r\\n url\\r\\n }\\r\\n cursor\\r\\n }\\r\\n pageInfo {\\r\\n endCursor\\r\\n hasNextPage\\r\\n }\\r\\n }\\r\\n }\\r\\n}\"}"
}

PayloadParameters (object)

Endpoints > PayloadParameters

A key-value list of HTTP parameters to add to the payload.

Each value can be either a number, string, Boolean, or a placeholder for a GraphQL query that you’ll enter separately, in the GraphQL queries section.

This property can only be used in a POST request. The parameters are sent as URL-encoded data in the request body. The Content-Type header is automatically set to application/x-www-form-urlencoded.

Dynamic values are supported when specified within the SubItems and SubQueries objects only.

Dynamic time expressions are also supported.

Example:

"PayloadParameters": {
  "type": "post",
  "expand": "true",
  "id": 120
}

Example:

You want to pass the following GraphQL query as a payload parameter:

query {
  user(login:"jsmith") {
    pullRequests(first:@pageSize, after:@offset) {
      totalCount
      edges {
        node {
          createdAt
          title
          url
        }
        cursor
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

When entering this query in the GraphQL queries section, you name it @MyFirstQuery.

Your source JSON configuration therefore contains the following:

"PayloadParameters": {
  "query": "@MyFirstQuery"
}

In sub-items and subqueries, should a dynamic value be invalid or unretrievable, the source skips the item, that is, the indexing process is dropped and Coveo moves on to the next item. In a permission subquery, however, an invalid or unretrievable dynamic value causes the source to stop crawling and to display an error in the Administration Console.

Note

PayloadParameters and PayloadJsonContent are mutually exclusive. In other words, if you provide payload parameters, you cannot provide a JSON object, and vice versa.

PermanentId (string)

Services > Endpoints > PermanentId

The PermanentId is an alternative, permanent unique item identifier.

When you expect the item Uri to change, this ensures that Coveo Machine Learning (Coveo ML) recognizes the items despite their new URI and associates them to the old data. So, in the future, if you modify or delete this source and reindex the same items, specifying the same item PermanentId format in your next configuration will ensure that ML doesn’t consider your items as new and rather picks up where it left off.

Dynamic values are supported.

Example:

{
  "Uri": "%[node.url]",
  "PermanentId": "%[sys_id]"
}

ProcessingAction (object)

Services > Endpoints > ProcessingAction

This object works similarly to the IndexingAction object.

When the Condition resolves to true, the Coveo crawler applies the specified action on the corresponding child items of an item. Possible actions are Process and Ignore, that is, the crawler can either index the subitems or ignore them.

A child item ignored with ProcessingAction isn’t indexed and therefore not visible in the Content Browser or a search interface.

If the condition resolves to false, it fallbacks to the default action, that is, Process.

Example:

"ProcessingAction": {
    "ActionOnItem": "Ignore",
    "Condition": "%[id]==1"
}

Like the IndexingAction object, the ProcessingAction object supports the following properties:

QueryParameters (object)

Services > Endpoints > QueryParameters

A key-value list of HTTP parameters to add to the query.

Each value can be either a number, string, Boolean, or a placeholder for a GraphQL query that you’ll enter separately, in the GraphQL queries section.

Dynamic values are supported when specified within the SubItems, SubQueries, and PermissionSubQueries arrays only. They aren’t supported in QueryParameters objects of a refresh endpoint.

Dynamic time expressions are also supported.

Example:

"QueryParameters": {
  "type": "post",
  "expand": "true",
  "id": 120
}

Example:

"QueryParameters": {
  "since": "@Now-6M",
  "until": "@Now"
}

Example:

You want to pass the following GraphQL query as a query parameter:

query {
  user(login:"jsmith") {
    pullRequests(first:@pageSize, after:@offset) {
      totalCount
      edges {
        node {
          createdAt
          title
          url
        }
        cursor
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
}

When entering this query in the GraphQL queries section, you name it @MyFirstQuery.

Your source JSON configuration therefore contains the following:

"QueryParameters": {
  "query": "@MyFirstQuery"
}

In sub-items and subqueries, should a dynamic value be invalid or unretrievable, the source skips the item, that is, the indexing process is dropped and Coveo moves on to the next item. In a permission subquery, however, an invalid or unretrievable dynamic value causes the source to stop crawling and to display an error in the Administration Console.

RefreshEndpoints (array)

Services > Endpoints > RefreshEndpoints

Each object in the RefreshEndpoints array is a refresh endpoint query to execute to retrieve added, updated, or deleted items when refresh is supported and performed.

A refresh endpoint is an endpoint that inherits from the parent endpoint definition. The refresh endpoint allows you to redefine the endpoint configuration properties. As a result, when you refresh your source, the properties defined under RefreshEndpoints override the properties defined under Endpoints. When you rescan or rebuild the source, however, the Endpoints properties apply.

Similarly, if you don’t specify any QueryParameters in the refresh endpoint definition, the endpoint query parameters will be inherited. However, either all query parameters are inherited, or none is. So, if you change one parameter, you must also redefine all other parameters that apply, even if they’re identical to those in the endpoint object.

Example

Your endpoint query parameters are the following:

"QueryParameters": {
  "type": "post",
  "workflow_state":"published",
  "since": "@RefreshDate",
  "expand": "true"
}

In your refresh endpoint configuration, you want to switch expand to false and keep all other query parameters identical, so you enter the following:

"QueryParameters": {
  "type": "post",
  "workflow_state":"published",
  "since": "@RefreshDate",
  "expand": "false"
}
Note

Dynamic values aren’t supported in the query parameters of a RefreshEndpoints object.

In addition to the Endpoints object configuration properties, the RefreshEndpoints object supports the following properties:

Example:

"RefreshEndpoints":[
  {
    "DateFormat":"\\'yyyy-MM-dd\\',\\'hh:mm:ss\\'",
    "QueryParameters":{
      "workflow_state":"published",
      "since": "@RefreshDate"
    }
  },
  {
    "IsDeletionQuery":true,
    "DateFormat":"\\'yyyy-MM-dd\\',\\'hh:mm:ss\\'",
    "QueryParameters":{
      "lastModifiedDate": "@Now-7d",
      "status":"Deleted"
    }
  },
  {
    "IsDeletionQuery":true,
    "DateFormat":"\\'yyyy-MM-dd\\',\\'hh:mm:ss\\'",
    "Path":"/api/table/audit_delete",
    "QueryParameters":{
      "tablename":"kb_knowledge",
      "since": "@RefreshDate"
    }
  },
  {
    "IsDeletedItem": "%[is_deleted]",
    "DateFormat":"\\'yyyy-MM-dd\\',\\'hh:mm:ss\\'",
    "QueryParameters":{
      "since": "@RefreshDate"
    }
  }
]
IsDeletionQuery (Boolean)

Services > Endpoints > RefreshEndpoints > IsDeletionQuery

Whether the defined query returns items to delete from the index. Default value is false, which means that all retrieved items are added to the index or updated. If the query returns items to add, update, and delete all at once, use the IsDeletedItem property instead.

IsDeletedItem (Boolean)

Services > Endpoints > RefreshEndpoints > IsDeletedItem

When a refresh query returns items to add, update, and delete all at once, this property allows you to specify which of these items should be deleted. Default value is false, but it’s considered to be true if IsDeletionQuery is set to true.

You can provide a dynamic value (for example, %[has_been_deleted_flag]) to be evaluated for each item or a static value.

Example:

"%[is_deleted]" deletes all items that have a "is_deleted": true JSON property flagging them as deleted.

"IsDeletedItem": %[is_deleted],
"DateFormat":"\\'yyyy-MM-dd\\',\\'hh:mm:ss\\'",
"QueryParameters":{
  "since": "@RefreshDate"
}
DeleteChildren (Boolean)

Services > Endpoints > RefreshEndpoints > DeleteChildren

Whether to delete children when the retrieved parent item is deleted. Default value is false. If the value is set to true, child items are deleted based on their Uri.

SubItems (array)

Services > Endpoints > SubItems

A list of sub-items to retrieve. Each sub-item is represented by a configuration object under Endpoints.

An item can have many different sub-items, for example, a blog post containing comments and attachments as child items. The SubItems object establishes a parent-child relationship between items. There’s no restriction on the number of sub-items an item can have.

In addition, sub-items can also have sub-items, for example if blog post comments also have attachments. In the application JSON response, these sub-items are nested within each other, and so should be your SubItems arrays in your source configuration.

To refer to the metadata of a parent item, prefix the metadata name with coveo_parent. You may also need to use raw.

Examples:

When the sub-items to index are located under a different endpoint, you provide the Path to their location.

"SubItems": [
  {
    "Path": "graphql",
    "Method": "GET",
    "ItemType": "Comment",
    "Uri": "%[node.url]",
    "ClickableUri": "%[node.url]",
    "Title": "%[node.title]",
    "ModifiedDate": "%[node.updated]",
    "Body": "%[node.content]",
    "Metadata": {
      "author": "%[node.author]",
      "createdby" :"%[coveo_parent.author]",
      "id": "%[id]"
    }
  }
]

Alternatively, when the desired sub-items are located under the same endpoint as their parent items (for example, the child item data is nested within the parent item data), you omit the Path property and provide the sub-items' location using the ItemPath property.

"SubItems": [
  {
    "ItemPath": "data.user.pullRequests.edges",
    "ItemType": "PullRequests",
    "Uri": "%[node.url]",
    "ClickableUri": "%[node.url]",
    "Title": "%[node.title]",
    "Body": "%[node.content]",
    "Metadata": {
      "author": "%[node.author]",
      "createdby" :"%[coveo_parent.author]",
      "id": "%[node.id]"
    }
  }
]

SubQueries (array)

Services > Endpoints > SubQueries

Each object in the SubQueries array represents a subquery to execute on every item in order to fetch additional metadata and/or the item body. Subqueries are especially useful when this information is located under a different path than that of the item.

To refer to the metadata of a parent item, prefix the metadata name with coveo_parent. You may also need to use raw.

Example:

"SubQueries": [
  {
    "Path": "graphql",
    "Method": "GET",
    "Body": "%[data.body]",
    "Metadata": {
      "created": "%[node.created]"
    }
  }
]

The subquery configuration supports the following properties from the Endpoints object configuration:

In addition, it supports the following property from the Services object configuration:

It also contains the following property:

IsThumbnail (Boolean)

Services > Endpoints > SubQueries > IsThumbnail

If the SubQueries object path leads to an image, set IsThumbnail to true to show this image as the thumbnail of an item.

The default value is false.

Supported thumbnail file formats are the following: .bmp, .emf, .exif, .gif, .icon, .jpeg, .png, .tiff, .wmf .

Notes
  • An Endpoint object can contain at most one subquery where IsThumbnail is set to true.

  • IsThumbnail and IsBinaryBody are mutually exclusive. In other words, if you set IsThumbnail to true, you must set IsBinaryBody to false, and vice versa.

Title (string)

Services > Endpoints > Title

The title of the item. Although this property isn’t required in the JSON configuration, we recommend that you include it, as the Content Browser displays its value.

Typically, Title contains a dynamic value, since a static, hardcoded value would make all item titles identical.

Example: "Title": "%[node.title]"

Url (string, required)

Services > Url

The Url value is the service URL of your web application.

Example: "Url": "https://api.github.com/"

Authentication (object)

Services > Authentication

If a service requires authentication, this object contains the service authentication configuration.

You must also enter authentication information in the Authentication section of the Add/Edit a GraphQL API Source panel.

Then:

  • If your source uses an HTTP, Basic, Kerberos, or NTLM authentication protocol, in the Authentication object, use the @Username and @Password placeholders to retrieve the values specified in the Add a GraphQL API source panel.

  • If your source uses an API key authentication protocol, include the @ApiKey placeholder in the HTTP headers, query parameters, or payload parameters.

    API key placeholder in JSON configuration
  • If your source uses the OAuth 2.0 authentication protocol, include the @ClientID, @ClientSecret, and @RefreshToken placeholders in the OAuth object.

The Authentication object supports the following properties:

Username (string)

Services > Authentication > Username

Username used to log in to the service. You can use @Username to retrieve the value specified in the Add a GraphQL API Source panel.

Password (string)

Services > Authentication > Password

Password used to log in to the service. This property can be empty even though a Username is specified. You can use @Password to retrieve the value specified in the Add a GraphQL API Source panel.

Domain (string)

Domain name to use when authenticating to a NTLM or Kerberos protected server.

ForceBasicAuthentication (Boolean)

Services > Authentication > ForceBasicAuthentication

Whether to force a basic HTTP header in the request. The default value is false.

OAuth (object)

If your application requires OAuth 2.0 authentication, add an OAuth object to your source configuration.

Your OAuth object must contain a Query object. Coveo will use the information in the Query object to make an authentication query to your application.

Optionally, your OAuth object may also contain a Response object. In this object, you may provide parameters such as AccessToken, TokenType, and ExpiresIn, whose values indicate where Coveo will find the corresponding information when parsing the API’s response. The Response object may also include the AuthorizationHeader parameter, whose value is the name of the authorization header that Coveo should use when querying your API for content.

Tip

Enter your client ID, client secret, and refresh token in the Add a GraphQL API source panel and use the @ClientId, @ClientSecret, and @RefreshToken placeholders in your JSON configuration.

This allows you to keep your confidential information obfuscated, thus preventing other Administration Console users to access it.

Refresh token placeholder in the source JSON configuration and in the source panel

Example:

"OAuth": {
  "Query": {
    "RefreshUrl": "http://example.com/token",
    "Method": "POST",
    "Parameters": {
      "grant_type": {
        "Type": "Payload",
        "Value": "refresh_token"
      },
      "refresh_token": {
        "Type": "Payload",
        "Value": "@RefreshToken",
        "IsRefreshToken": true
      },
      "client_id": {
        "Type": "Payload",
        "Value": "@ClientId"
      },
      "client_secret": {
        "Type": "Payload",
        "Value": "@ClientSecret"
      }
    }
  },
  "Response": {
    "AccessToken": "access_token",
    "SupportsRefreshToken" : "true",
    "RefreshToken": "refresh_token",
    "ExpiresIn": "expires_in",
    "TokenType": "token_type"
  }
}

The OAuth object supports the following objects:

Query (object, required)

If your application requires OAuth 2.0 authentication, you must add an OAuth object to your source configuration.

Your OAuth object must contain a Query object. Coveo will use the information in the Query object to make an authentication query to your application.

Tip

Enter your client ID, client secret, and refresh token in the Add a GraphQL API source panel and use the @ClientId, @ClientSecret, and @RefreshToken placeholders in your JSON configuration.

This allows you to keep your confidential information obfuscated, thus preventing other Administration Console users to access it.

Refresh token placeholder in the source JSON configuration and in the source panel

Example:

"Query": {
  "RefreshUrl": "http://example.com/token",
  "Method": "POST",
  "Parameters": {
    "grant_type": {
      "Type": "Payload",
      "Value": "refresh_token"
    },
    "refresh_token": {
      "Type": "Payload",
      "Value": "@RefreshToken",
      "IsRefreshToken": true
    },
    "client_id": {
      "Type": "Payload",
      "Value": "@ClientId"
    },
    "client_secret": {
      "Type": "Payload",
      "Value": "@ClientSecret"
    }
  }
}

The Query object supports the following properties:

RefreshUrl (string, required)

Services > Authentication > OAuth > Query > RefreshUrl

If your application requires OAuth 2.0 authentication, your Query object must include a RefreshUrl property. The RefreshUrl value must be a URL that Coveo will use to refresh its access token.

Example
"Query": {
  "RefreshUrl": "http://example.com/token",
  "Method": "POST",
  "Parameters": {
    "grant_type": {
      "Type": "Payload",
      "Value": "refresh_token"
    },
    "refresh_token": {
      "Type": "Payload",
      "Value": "@RefreshToken",
      "IsRefreshToken": true
    },
    "client_id": {
      "Type": "Payload",
      "Value": "@ClientId"
    },
    "client_secret": {
      "Type": "Payload",
      "Value": "@ClientSecret"
    }
  }
}
OAuth query Headers (object)

If your application requires OAuth 2.0 authentication, your Query object can optionally include a Headers object.

When making an authentication query to your application, Coveo will add these HTTP headers to its request.

Note

Coveo automatically sets the Content-Type header. Therefore, you don’t need to add it to the Headers object.

Example:

"Query": {
  "RefreshUrl": "http://example.com/token",
  "Headers": {
    "X-Auth": "apikey1234567890abcdef"
  }
}
OAuth query Method (string enum)

If your application requires OAuth 2.0 authentication, your Query object can optionally include a Method property.

The Method property specifies the HTTP method that Coveo should use when refreshing its token. Default is POST.

Example
"Query": {
  "RefreshUrl": "http://example.com/token",
  "Method": "POST",
  "Parameters": {
    "grant_type": {
      "Type": "Payload",
      "Value": "refresh_token"
    },
    "refresh_token": {
      "Type": "Payload",
      "Value": "@RefreshToken",
      "IsRefreshToken": true
    },
    "client_id": {
      "Type": "Payload",
      "Value": "@ClientId"
    },
    "client_secret": {
      "Type": "Payload",
      "Value": "@ClientSecret"
    }
  }
}
OAuth query Parameters (object)

Services > Authentication > OAuth > Query > Parameters

If your application requires OAuth 2.0 authentication, your Query object can optionally include query parameters for Coveo to use.

Each object in the Parameters object represents a parameter to include in Coveo’s authentication request to your application. Each object should contain a "Type" and a "Value" property.

The Type property indicates how to include the parameter in the request. Possible values for this property are query or payload.

In addition, if you include a refresh_token parameter object, you should also add a IsRefreshToken property with a value of true to this object.

Tip

Enter your client ID, client secret, and refresh token in the Add a GraphQL API source panel and use the @ClientId, @ClientSecret, and @RefreshToken placeholders in your JSON configuration.

This allows you to keep your confidential information obfuscated, thus preventing other Administration Console users to access it.

Refresh token placeholder in the source JSON configuration and in the source panel

Example:

"Query": {
  "RefreshUrl": "http://example.com/token",
  "Method": "POST",
  "Parameters": {
    "grant_type": {
      "Type": "Payload",
      "Value": "refresh_token"
    },
    "refresh_token": {
      "Type": "Payload",
      "Value": "@RefreshToken",
      "IsRefreshToken": true
    },
    "client_id": {
      "Type": "Payload",
      "Value": "@ClientId"
    },
    "client_secret": {
      "Type": "Payload",
      "Value": "@ClientSecret"
    }
  }
}
Response (object)

Services > Authentication > OAuth > Response

If your application requires OAuth 2.0 authentication, you can optionally add a Response object to your OAuth object.

The Response object contains, among other things, the properties that Coveo must extract from the authentication server’s response. The value of each property represents the path to the corresponding value in the response.

In the Response object, you may also enter other authentication parameters, such as the AuthorizationHeader and SupportsRefreshToken properties.

Example:

If the authentication server’s response looks like this:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token": "jOs0PoLKm61sd6h49",
  "refresh_token": "QpMas-tuI9bvFp01-Xxpl04gC_0m",
  "token_type": "bearer",
  "expires_in": 86400
}

Then your Response object should look like this:

"Response": {
  "AccessToken": "access_token",
  "SupportsRefreshToken" : "true",
  "RefreshToken": "refresh_token",
  "ExpiresIn": "expires_in",
  "TokenType": "token_type"
}

The Response object supports the following properties:

AccessToken (string)

Services > Authentication > OAuth > Response > AccessToken

If your application requires OAuth 2.0 authentication, you can optionally add a Response object to your OAuth object. Coveo will then extract the information from the API’s response using the values specified in the Response object.

In the Response object, you can add the AccessToken property to specify the path to the access token in the API’s response. Default is access_token.

Example

If the authentication server’s response looks like this:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token": "jOs0PoLKm61sd6h49",
  "refresh_token": "QpMas-tuI9bvFp01-Xxpl04gC_0m",
  "token_type": "bearer",
  "expires_in": 86400
}

Then your Response object should look like this:

"Response": {
  "AccessToken": "access_token",
  "SupportsRefreshToken" : "true",
  "RefreshToken": "refresh_token",
  "ExpiresIn": "expires_in",
  "TokenType": "token_type"
}
SupportsRefreshToken (Boolean)

Services > Authentication > OAuth > Response > SupportsRefreshToken

If your application requires OAuth 2.0 authentication, you can optionally add a Response object to your OAuth object.

In the Response object, you can add the SupportsRefreshToken property to indicate whether your application’s OAuth 2.0 flow supports refresh tokens. Default is true.

Example

If the authentication server’s response looks like this:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token": "jOs0PoLKm61sd6h49",
  "refresh_token": "QpMas-tuI9bvFp01-Xxpl04gC_0m",
  "token_type": "bearer",
  "expires_in": 86400
}

Then your Response object should look like this:

"Response": {
  "AccessToken": "access_token",
  "SupportsRefreshToken" : "true",
  "RefreshToken": "refresh_token",
  "ExpiresIn": "expires_in",
  "TokenType": "token_type"
}
RefreshToken (string)

Services > Authentication > OAuth > Response > RefreshToken

If your application requires OAuth 2.0 authentication, you can optionally add a Response object to your OAuth object. Coveo will then extract the information from the API’s response using the values specified in the Response object.

In the Response object, you can add the AccessToken property to specify the path to the refresh token in the API’s response. Default is refresh_token.

Example

If the authentication server’s response looks like this:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token": "jOs0PoLKm61sd6h49",
  "refresh_token": "QpMas-tuI9bvFp01-Xxpl04gC_0m",
  "token_type": "bearer",
  "expires_in": 86400
}

Then your Response object should look like this:

"Response": {
  "AccessToken": "access_token",
  "SupportsRefreshToken" : "true",
  "RefreshToken": "refresh_token",
  "ExpiresIn": "expires_in",
  "TokenType": "token_type"
}
ExpiresIn (string)

If your application requires OAuth 2.0 authentication, you can optionally add a Response object to your OAuth object. Coveo will then extract the information from the API’s response using the values specified in the Response object.

In the Response object, you can add the ExpiresIn property to specify the path to the refresh token expiration delay in the API’s response. Default is expires_in.

If the API’s response doesn’t contain an expiration delay, use the ExpiresInDefaultValue property instead.

Example

If the authentication server’s response looks like this:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token": "jOs0PoLKm61sd6h49",
  "refresh_token": "QpMas-tuI9bvFp01-Xxpl04gC_0m",
  "token_type": "bearer",
  "expires_in": 86400
}

Then your Response object should look like this:

"Response": {
  "AccessToken": "access_token",
  "SupportsRefreshToken" : "true",
  "RefreshToken": "refresh_token",
  "ExpiresIn": "expires_in",
  "TokenType": "token_type"
}
ExpiresInDefaultValue (number)

Services > Authentication > OAuth > Response > ExpiresInDefaultValue

If your application requires OAuth 2.0 authentication, you can optionally add a Response object to your OAuth object. Coveo will then extract the information from the API’s response using the values specified in the Response object.

Typically, the authentication server will return an expiration delay for its refresh token, which you can extract with the ExpiresIn property. However, if the API’s response doesn’t include an expiration delay, you can add the ExpiresInDefaultValue property to your Response object.

The ExpiresInDefaultValue value specifies the number of seconds after which Coveo should consider the refresh token expired. Default is 3600.

Example:

"Response": {
  "AccessToken": "access_token",
  "SupportsRefreshToken" : "true",
  "RefreshToken": "refresh_token",
  "ExpiresInDefaultValue": 1800,
  "TokenType": "token_type"
}
TokenType (string)

If your application requires OAuth 2.0 authentication, you can optionally add a Response object to your OAuth object. Coveo will then extract the information from the API’s response using the values specified in the Response object.

In the Response object, you can add the ExpiresIn property to specify the path to the token type in the API’s response. Default is token_type.

If the response doesn’t specify a token type or if it’s invalid or inappropriate, Coveo will use Bearer by default. If you want a different default value, use the TokenTypeDefaultValue property instead.

Example

If the authentication server’s response looks like this:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token": "jOs0PoLKm61sd6h49",
  "refresh_token": "QpMas-tuI9bvFp01-Xxpl04gC_0m",
  "token_type": "bearer",
  "expires_in": 86400
}

Then your Response object should look like this:

"Response": {
  "AccessToken": "access_token",
  "SupportsRefreshToken" : "true",
  "RefreshToken": "refresh_token",
  "ExpiresIn": "expires_in",
  "TokenType": "token_type"
}
TokenTypeDefaultValue (string)

Services > Authentication > OAuth > Response > TokenTypeDefaultValue

If your application requires OAuth 2.0 authentication, you can optionally add a Response object to your OAuth object. Coveo will then extract the information from the API’s response using the values specified in the Response object.

Typically, the authentication server will return a token type, which you can extract with the TokenType property. If the API’s response doesn’t specify a token type, or if the token type is invalid or inappropriate, Coveo will use Bearer by default.

However, if you want Coveo to use a different default token type, you can specify it by the TokenTypeDefaultValue property to your Response object.

AuthorizationHeader (string)

Services > Authentication > OAuth > Response > AuthorizationHeader

If your application requires OAuth 2.0 authentication, you can optionally add a Response object to your OAuth object.

In the Response object, you can add the AuthorizationHeader property to indicate the name of the authorization header that Coveo should use to provide its access token when querying your API for content.

Refer to your API’s documentation for the header name to use. Default is Authorization.

Notes

Coveo automatically adds the specified authorization header to its content requests to your application. Do not add this header to the Headers object of your service.

Example:

If your API documentation specifies that the access token must be provided in a header named X-ACCESS-TOKEN, then your Response object should specify it like this:

"Response": {
  "AccessToken": "access_token",
  "SupportsRefreshToken" : "true",
  "RefreshToken": "refresh_token",
  "ExpiresIn": "expires_in",
  "TokenType": "token_type",
  "AuthorizationHeader": "X-ACCESS-TOKEN"
}

As a result, when making content requests to your application, Coveo will automatically include an X-ACCESS-TOKEN header with the access token value.

{
  "headers": {
    "Content-Type": "application/json",
    "X-ACCESS-TOKEN": "123456789abcdef"
  }
}

Headers (object)

Services > Headers

A key-value list of HTTP headers to add to the query. Each value can be either a number, string, or Boolean.

The Headers object is inheritable.

Example:

"Headers": {
  "accept": "application/vnd.github.v3+json",
  "User-Agent": "PostmanRuntime/7.29.0"
}
Note

Unlike a browser or a tool such as Postman, Coveo doesn’t automatically add a User-Agent header to your request. GraphQL APIs typically don’t require a User-Agent header. However, if your API does require it, add it to the query Headers object.

Paging (object)

Services > Paging

In the Paging object, specify how you want the content to be paged.

This property is inheritable.

Then, in your GraphQL query, make sure to include tokens @pageSize and @offset.

Coveo will replace @pageSize with the value of the pageSize parameter of your paging configuration. Similarly, @offset will be replaced with the value extracted from the response using either the NextPageKey or the OffsetStart parameter, depending on the paging method selected in OffsetType.

Example:

"paging": {
  "pageSize": 10,
  "offsetType": "cursor",
  "nextPageKey": "data.user.pullRequests.pageInfo.endCursor"
},
"PayloadJsonContent": "@MyFirstQuery"

The Paging object supports the following properties:

OffsetType (string enum, required)

Services > Paging > OffsetType

The type of information on which the offset is based. Possible values are page, item, url, and cursor.

  • page: An offset per page is based on the page number, that is, each paginated call increments the offset by 1.

    Example

    The offset of the following calls is based on the page number:

    • http://example.com/api/item?limit=10&page=0

    • http://example.com/api/item?limit=10&page=1

  • item: An offset based on the item number increments the offset by the number of items in each page.

    Example

    The offset of the following calls is based on the item number:

    • http://example.com/api/item?limit=10&start=0

    • http://example.com/api/item?limit=10&start=10

  • url: A URL-based offset retrieves the next page (offset) URL with the NextPageKey in the JSON response, and the next call is a request to this URL.

    Example

    The following links could be returned in the web application response as values of NextPageKey. When you choose to use a URL-based object, Coveo sends a request to this URL to retrieve your content.

    • http://example.com/api/item?limit=5

    • http://example.com/api/item?page=3d170d80d8n3n2342c328s

  • cursor: An offset based on the cursor retrieves the next page cursor using the NextPageKey in the JSON response and builds the next page URL.

    Example

    The offset of the following calls is based on the page cursor:

    • http://example.com/api/item?limit=5

    • http://example.com/api/item?limit=5&pageToken=3d170d80-7b3b-4371-9499-2ec6a78c507e

PageSize (number, required)

Services > Paging > PageSize

The number of items to fetch per page.

Example: With paging URL https://example.com/api/item?position=0&quantity=50, your JSON configuration should include "PageSize": 50.

NextPageKey (string)

Services > Paging > NextPageKey

When the OffsetType value is "url" or "cursor", provide the path (simple path or JSONPath) to the key representing the value of the next page reference, that is, either the next page URL or the next page cursor.

The NextPageKey property isn’t required when the OffsetType value is page or item.

Example: "NextPageKey": "NextPageLink"

OffsetStart (number)

Services > Paging > OffsetStart

Offset of the first page to fetch. This property is required when the OffsetType value is "page" or "item".

Example: Your first paging URL is https://example.com/api/item?position=0&quantity=50. If you want to retrieve all items except items 1 to 50, your paging configuration must include "OffsetStart": 1.

TotalCountHeaderKey (string)

Services > Paging > TotalCountHeaderKey

The name of an HTTP header whose value represents the total number of items retrieved through the API call. This property is useful when Coveo makes an API call to a page that doesn’t exist, causing an error to be returned.

However, when using this property, you must be sure that the total always matches the actual number of items returned by your API, as Coveo’s crawler uses this total as an indication to stop. Should the expected total be lower than the actual number of items returned, Coveo won’t index the remaining items.

Therefore, if your API supports it, we recommend using the FetchNextPageUntilNoResult property instead, as a safer alternative.

On the other hand, if the expected total is higher than the actual number of items returned, Coveo’s crawler will throw an error after 10 empty pages. In such a case, you can download the activity logs to review the TotalCountKey value that Coveo retrieved, and then adjust your source configuration accordingly.

Example: "TotalCountHeaderKey": "x-total-count"

TotalCountKey (string)

Services > Paging > TotalCountKey

The path (simple path or JSONPath) to a response body property representing the total number of items retrieved through the API call. This property is useful when Coveo makes an API call to a page that doesn’t exist, causing an error to be returned.

However, when using this property, you must be sure that the total always matches the actual number of items returned by your API, as Coveo’s crawler uses this total as an indication to stop. Should the expected total be lower than the actual number of items returned, Coveo won’t index the remaining items.

Therefore, if your API supports it, we recommend using the FetchNextPageUntilNoResult property instead, as a safer alternative.

On the other hand, if the expected total is higher than the actual number of items returned, Coveo’s crawler will throw an error after 10 empty pages. In such a case, you can download the activity logs to review the TotalCountKey value that Coveo retrieved, and then adjust your source configuration accordingly.

Example: "TotalCountKey": "retrievedContent.totalCount"

Permissions (array)

Services > Permissions

Each object in the Permissions array represents a permission level. In turn, permission levels contain one or more PermissionsSets arrays.

The Permissions array is required when you select the Same users and groups as in your content system source content security option. It contains the permission levels and permission sets to apply to the items indexed through this service. The members listed in these levels and sets are either allowed or denied access to the indexed items.

For more information on sources that index permissions and on how Coveo handles these permissions, see Coveo management of security identities and item permissions.

This property is inheritable.

Example:

"Permissions": [
  {
    "Name": "Permission Level 1",
    "PermissionsSets": [
      {
        "Name": "Permission Set 1",
        "AllowedMembers": [
          {
            "Name": "jsmith@example.com",
            "Type": "User",
            "AdditionalInfo": {
              "title": "%[customMetadata]"
            }
          }
        ],
        "DeniedMembers": null,
        "IsAnonymousAllowed": false
      }
    ]
  }
]

The Permissions array supports the following properties:

Permission level Name (string)

The name of the permission level.

PermissionsSets (array)

Services > Permissions > PermissionsSets

The PermissionsSets array specifies who can or can’t access the indexed items. Each object in the array describes a single permission set, which can contain lists of allowed and denied members.

For more information on sources that index permissions and on how Coveo handles these permissions, see Coveo management of security identities and item permissions.

Objects in the PermissionsSets array support the following properties:

Permission set Name (string)

The Name property indicates the name of the permission set.

AllowedMembers and DeniedMembers arrays

Services > Permissions > PermissionsSets > AllowedMembers/DeniedMembers

Each object in the AllowedMembers and DeniedMembers arrays represents a member security identity that should be allowed or denied to access the indexed content.

Note

If a user is listed under both AllowedMembers and DeniedMembers for an item, the denial prevails so that security holes are avoided.

For more information on sources that index permissions and on how Coveo handles these permissions, see Coveo management of security identities and item permissions.

The following is an example of a simple situation where, in your permission system, security identities are identified with email addresses. Your source will work with the Email security identity provider to ensure that your search interface users only see the content they’re allowed to.

If your permission system is more complex, requires a security provider other than Email, or is frequently updated, you should not only index allowed and denied security identities, but also provide a permission configuration instructing Coveo on how to index your permission system.

Example

You index text items written by different people. The metadata of each item contains the key author, and, in this system, authors are identified by their email address. These addresses are therefore expected as values of the Name field. With the following configuration, each user in your organization can access the items they have created through your Coveo-powered search interfaces.

"PermissionsSets": [
  {
    "Name": "Permission Set 1",
    "AllowedMembers": [
      {
        "Name": "%[author]",
        "Type": "User",
        "Condition": "%[published] == true",
        }
    ],
    "DeniedMembers": null,
    "IsAnonymousAllowed": false
  }
]

AllowedMembers and DeniedMembers arrays support the following properties:

Member Name (string, required)

The name of the member security identity.

In simple use cases similar to that described under AllowedMembers and DeniedMembers arrays, this should be an email address.

Dynamic values are supported.

Type (string enum, required)

The type of member. Allowed values are User, Group, and VirtualGroup.

For more information on these types of security identities, see Coveo management of security identities and item permissions.

Permission Condition (string)

The Condition value is a condition that must resolve to true for the security identity specified in Name to be resolved, that is, extracted by the security identity provider. As a result, the permission applies.

When the condition resolves to false, the security identity is not resolved and the corresponding permission doesn’t apply.

Adding a condition to your AllowedMembers or DeniedMembers object is optional.

To write your condition, use the same syntax as for indexing pipeline extension conditions. Conditions can be assembled using the following operators: AND, OR, Exists, NOT, >, and <. Parentheses are also supported to specify operation order.

The metadata fields in your condition must either be defined in the Metadata object of the source configuration or referenced with raw. You can specify an array if the metadata refers to a multi-value field in your repository. Dynamic values are also supported.

Example

You index a list of available and discontinued products, and your public search interface is used by both your employees and your customers. On this search interface, your employees can log in to see additional content, while customers can’t log in.

You want to hide your discontinued products from your customers only, so you use the Condition parameter to apply a permission to these items. As a result, all products with Discontinued: yes in their metadata are visible to members of the *@mycompany.com group only, that is, your employees, while non-discontinued products are available to all search interface users.

"PermissionsSets": [
  {
    "Name": "Permission Set 1",
    "AllowedMembers": [
      {
        "Name": "*@mycompany.com",
        "Type": "Group",
        "Condition": "%[discontinued] == yes"
      }
    ],
    "DeniedMembers": null,
    "IsAnonymousAllowed": true
  }
]

For more information on sources that index permissions and on how Coveo handles these permissions, see Coveo management of security identities and item permissions.

PermissionType (string)

This parameter is relevant only when you provide a permission configuration.

The PermissionType is a key representing the configuration on how to extract all relationships of the security identity specified in Name. The security identity provider will use this configuration when processing the security identity.

In the Content Security tab of the Add/Edit a GraphQL API Source panel, you’ll need to select the Same users and groups as in your content system, and then to provide a JSON permission configuration detailing how to retrieve the relationships of each security identity and how to index this data.

For more information on sources that index permissions and on how Coveo handles these permissions, see Coveo management of security identities and item permissions.

AdditionalInfo (object)

This parameter is relevant only when you provide a permission configuration.

The AdditionalInfo object is a key-value store of additional information required by some security providers. Each key represents the metadata name of the repository item, while its value is the value path (simple path or JSONPath) in the JSON response.

When writing your permission configuration, you can use coveo_parent to refer to the information retrieved with the AdditionalInfo parameter of a permission subquery.

Dynamic values are supported in the values of this object.

IsAnonymousAllowed (Boolean)

Permissions > PermissionsSets > IsAnonymousAllowed

The IsAnonymousAllowed property indicates whether anonymous, that is, unauthenticated users are allowed to access the retrieved items. Default value is false.

For more information on sources that index permissions and on how Coveo handles these permissions, see Coveo management of security identities and item permissions.

PermissionsFromMetadata array

Services > Permissions > PermissionsSets > PermissionsFromMetadata

This array is relevant only when you provide a permission configuration.

The PermissionsFromMetadata array is an alternative to the PermissionSubQueries array, as it fetches permission data, typically the security identities that are allowed or denied access to the item. This data is crucial to retrieve if you want to replicate the application’s permission system in Coveo.

Include a PermissionsFromMetadata array in your source configuration when the permission data appears in the metadata of an item. Conversely, a PermissionSubQueries array should be used when an item and its permission data must be retrieved with two different queries.

For more information on sources that index permissions and on how Coveo handles these permissions, see Coveo management of security identities and item permissions.

Objects of the PermissionsFromMetadata array support:

PermissionSubQueries array

Services > Permissions > PermissionsSets > PermissionSubQueries

This array is relevant only when you provide a permission configuration.

Each object in the PermissionSubQueries array represents a subquery to execute on every item to fetch permission data, typically the security identities that are allowed or denied access to the item. This data is crucial to retrieve if you want to replicate the application’s permission system in Coveo.

The PermissionSubQueries array is an alternative to the PermissionsFromMetadata array.

Include a PermissionSubQueries array in your source configuration when an item and its permission data must be retrieved with two different queries. Conversely, the PermissionsFromMetadata array should be used when the permission data appears in the metadata of an item.

For more information on sources that index permissions and on how Coveo handles these permissions, see Coveo management of security identities and item permissions.

Objects of the PermissionSubQueries array support:

Example:

"permissionSubQueries": [
  {
    "ItemPath": "permissions",
    "Path": "%[productid]/permissions",
    "Method": "GET",
    "QueryParameters": {},
    "Name": "%[name]",
    "Type": "group",
    "PermissionType": "config1",
    "Condition": "%[field] == value",
    "IsAllowedMember": true,
    "AdditionalInfo":
      {
        "PermissionID": "%[id]",
        "PermissionName": "%[name]"
      }
  }
]
IsAllowedMember (Boolean)

The IsAllowedMember property indicates whether the specified member is allowed to access the item. Default value is false.

For more information on sources that index permissions and on how Coveo handles these permissions, see Coveo management of security identities and item permissions.

StringItemPath (string)

Services > Permissions > PermissionsSets > StringItemPath

The path to the item in the JSON response returned by your API.

When indexing permissions with PermissionSubQueries, use StringItemPath in place of ItemPath if your API returns the list of identities in an array rather than as a series of objects.

Then, use value %[item] to tell Coveo where you want to store each of the identities extracted from the permission array. The Name property is an appropriate place.

Read more on StringItemPath vs. ItemPath

Most APIs return permissions as a series of objects such as:

{
  "allowed": [
    {
      "email": "jsmith@example.com"
    },
    {
      "email": "ballen@example.com"
    }
  ]
}

In such a case, you would use ItemPath to extract permissions.

However, if your API rather returns permissions as follows, you should use StringItemPath instead.

{
  "allowed": ["jsmith@example.com", "ballen@example.com"]
}
Example

If you expect your API to return permissions in an array such as:

{
  "allowedusers": ["jsmith@example.com", "ballen@example.com"]
}

Include the following in your permission subquery: "StringItemPath": "allowedusers".

In addition, to index the extracted user identities under Name, add: "Name": %[item].

Your permission subquery therefore looks as follows:

"permissionSubQueries": [
  {
    "StringItemPath": "allowedusers",
    "Path": "item/location",
    "Method": "GET",
    "Name": "%[item]",
    "Type": "User",
    "IsAllowedMember": true
  }
]

StringItemPath can appear in PermissionSubQueries objects only.

Note

ItemPath and StringItemPath are mutually exclusive. In other words, if you use StringItemPath in a subquery, you can’t also use ItemPath, and vice versa.

SkippableErrorCodes (string)

Services > SkippableErrorCodes

When crawling your content, Coveo may encounter an HTTP error and stop. If you expect the web application API to return an error and want it to be ignored so that the crawling process continues, specify the error code as the SkippableErrorCodes property value.

This property is inheritable. When you set it at the service level, it will apply to all endpoints in this service, and subqueries in these endpoints. You can override the service-level configuration by setting the SkippableErrorCodes property again at the endpoint or subquery level. Sub-items don’t inherit this property.

Use a semicolon (;) to separate error codes.

Example: "SkippableErrorCodes": "500;404;403"