Authorisation

The GraphQL endpoints at Bipsync use OAuth for authentication. Completion documentation for using OAuth to authenticate with the Bipsync API is available at https://docs.bipsync.com/docs/oauth/.

GraphQL uses granular OAuth scopes. Ensure that these are configured for your OAuth application, and that you have passed them in when getting an access token. See the OAuth Scopes documentation for further details.

When an OAuth token is granted that identifies the request on behalf of a user (e.g. Authorization Code Grant) only the data accessible by that user will be available through GraphQL requests.

When an OAuth token is granted that identifies a team (e.g. Client Credentials Grant) but not a user, all data accessible to that team will be available through GraphQL requests.

HTTP Requests

The endpoint for sending GraphQL requests to is a POST request to/v1/graphql. The GraphQL over HTTP specification defines three primary query parameters for requests:

query: A required string containing the GraphQL query document. This is the entire GraphQL query string, which must be URL-encoded.

variables: An optional JSON-encoded string that contains any variables the query uses.

operationName: An optional string that is required when the query document contains multiple named operations. It specifies which operation should be executed.

For more info on these see https://graphql.org/learn/queries/.

Example

> POST /v1/graphql HTTP/1.1
> Host: client-api.bipsync.com
> Content-Type: application/json
> Accept: */*
> Content-Length: 342

| {
|   "query": "query GetTasksByPriority($priority: TaskPriority!) {\n    tasks(filter: { priority: $priority }) {\n        edges {\n            node {\n                id\n                name\n                priority\n            }\n        }\n    }\n}",
|   "operationName": "GetTasksByPriority",
|   "variables": {
|     "priority": "HIGH"
|   }
| }

HTTP Status Codes

The GraphQL endpoint can return the following HTTP status codes:

Status Code	Type	Description
200	OK	The usage of HTTP status codes in GraphQL differs from the REST API. The GraphQL API can return a `200` status code for failed queries. See Error Handling for more details.
400	Bad Request	The request contains invalid data. Ensure that no request parameters are missing and that all supplied values are valid. See the HTTP Requests section above for the allowed/required parameters.
401	Unauthorized	Authentication failed for the request. Ensure the access token is valid, is passed to the API correctly and has the required scope.
403	Forbidden	The originating IP address is not permitted to access the API.
429	Too Many Requests	Too many API requests have been made and rate limiting is being enforced.
500	Internal Server Error	A server error occurred. Try the request again after a short while.

Error Handling

GraphQL can return a 200 status code for failed queries. For example if the query does not use correct GraphQL syntax.

It is important to check for an errors field in the JSON response. If present, this will be an array of errors that occurred during query execution.

The following example shows the JSON response to a GraphQL query that includes a field that is not defined in the schema:

{
  "errors": [
    {
      "message": "Cannot query field \"badField\" on type \"File\". Did you mean \"fields\"?",
      "locations": [
        {
          "line": 7,
          "column": 9
        }
      ]
    }
  ]
}