# Basics

# 1 Authenticating with the Web API

There are two ways of authenticating with the Web API:

With an integrator account, using e-mail and password.
With an integration installation, using an access key.

# Example request

Authenticate as an integrator by providing your email and password as basic authentication values:

POST https://api.gestal.cloud/auth 'Authorization: Basic <user:password>'

For sake of simplicity, examples through this documentation will only illustrate the concept of the requests. Many free HTTP clients are available to do initial tests with the API, such as Insomnia (opens new window), HTTPie (opens new window), Postman (opens new window), or curl (opens new window).

Real examples

HTTP client and code examples are covered in the following chapters.

# Example Response

Once successful, a session token will be provided in response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpX..."
}

# Example Authenticated Request

Session token must be provided for every request made as an integrator:

GET https://api.gestal.cloud/auth 'Authorization: Bearer <token>'

Treat tokens with care

Never store a token, it will expire after 24 hours anyway.

# 3 Errors

Web API uses conventional HTTP response codes to indicate the request's success or failure. 2xx codes range are for successful responses, 4xx represents an error in provided request (wrong credentials, expired session token, missing attribute in payload, etc.). 5xx codes indicate an error in our servers and will be automatically reported to us.

# 4 HTTP status code summary

Code	Name	Description
`200`	OK	Request is successful. Everything worked as expected.
`201`	Created	Resource is successfully created.
`202`	Accepted	Operation is accepted but will be processed in background.
`204`	No Content	Everything worked as expected, but nothing to respond.
`400`	Bad Request	Unacceptable request, mandatory conditions were not met.
`401`	Unauthorized	Invalid credentials, session token is expired, etc.
`403`	Forbidden	Resource is not accessible due to authorization failure.
`404`	Not Found	Resource cannot be found.
`405`	Method Not Allowed	Recognized request, HTTP method was rejected.
`422`	Unprocessable Entity	Operation on resource failed, often due to a validation error.
`429`	Too Many Request	Raised when you have been rate-limited by our API protections due to flood detection. Please wait 2 hours and contact us if the situation persists longer than that.
`5xx`	Server Error	Error on Vision API side (will be automatically reported to us).

# JSON Error feedback

In addition to HTTP response codes, a descriptive message is returned by the API in case of request failure, helping you identifying where it went wrong. Here are a few examples:

# Failed authentication

{
  "message": "authentication_failed"
}

# Missing parameter

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "traceId",
  "errors": {
    "$.vendor_id": [
      "The vendor_id field is required."
    ]
  }
}

# Wrong value type

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "traceId",
  "errors": {
    "$.pin_tag": [
      "The JSON value could not be converted to System.String. Path: $[0].pin_tag | LineNumber: 2 | BytePositionInLine: 16."
    ]
  }
}

# Unique ID already used

{
  "message": "Vendor id is already taken."
}

# Multiple errors in bulk data

When submitting bulk data, errors will be marked by the index of the entry in your JSON array.

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "traceId",
  "errors": {
    "[0].vendor_id": [
      "The vendor_id field is required."
    ]
  }
}

← Introduction HTTP Client Tutorial →