Authentication

Some of the API requests (especially the ones that are read-only GET requests) do not require any authentication. The other ones, that modify data into the database, require broker authentication via API key. Additionally, owner tokens are issued to facilitate multiple actor roles upon object creation.

API keys

Basic Authenication

API key is username to use with Basic Authentication scheme (see RFC 2617#section-2).

Bearer Authenication

API key is token to use with Bearer Authentication scheme

Owner tokens

Getting token

The token is issued when object is created in the database:

Request

POST /api/2.5/tenders?opt_pretty=1 HTTP/1.0
Authorization: Bearer broker
Content-Type: application/json
Host: lb-api-sandbox.prozorro.gov.ua

{
  "data": {
    "title": "футляри до державних нагород",
    "title_en": "Cases with state awards",
    "title_ru": "футляры к государственным наградам",
    "procuringEntity": {
      "name": "Державне управління справами",
      "identifier": {
        "scheme": "UA-EDR",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "address": {
        "countryName": "Україна",
        "postalCode": "01220",
        "region": "м. Київ",
        "locality": "м. Київ",
        "streetAddress": "вул. Банкова, 11, корпус 1"
      },
      "contactPoint": {
        "name": "Державне управління справами",
        "telephone": "+0440000000"
      },
      "kind": "general"
    },
    "value": {
      "amount": 500,
      "currency": "UAH"
    },
    "minimalStep": {
      "amount": 5,
      "currency": "UAH"
    },
    "items": [
      {
        "id": "df827a0a87354ad59f985d4b31bbaf6c",
        "description": "футляри до державних нагород",
        "description_en": "Cases with state awards",
        "description_ru": "футляры к государственным наградам",
        "classification": {
          "scheme": "ДК021",
          "id": "44617100-9",
          "description": "Cartons"
        },
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "17.21.1",
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ],
        "unit": {
          "name": "кілограм",
          "code": "KGM",
          "value": {
            "amount": 6
          }
        },
        "quantity": 5,
        "relatedLot": "9217965f43384438ac7af4b14e4fc52a"
      }
    ],
    "enquiryPeriod": {
      "endDate": "2023-10-17T00:00:00+02:00"
    },
    "tenderPeriod": {
      "endDate": "2023-10-24T00:00:00+02:00"
    },
    "procurementMethodType": "belowThreshold",
    "mode": "test",
    "features": [
      {
        "code": "OCDS-123454-AIR-INTAKE",
        "featureOf": "item",
        "relatedItem": "df827a0a87354ad59f985d4b31bbaf6c",
        "title": "Потужність всмоктування",
        "title_en": "Air Intake",
        "description": "Ефективна потужність всмоктування пилососа, в ватах (аероватах)",
        "enum": [
          {
            "value": 0.1,
            "title": "До 1000 Вт"
          },
          {
            "value": 0.15,
            "title": "Більше 1000 Вт"
          }
        ]
      },
      {
        "code": "OCDS-123454-YEARS",
        "featureOf": "tenderer",
        "title": "Років на ринку",
        "title_en": "Years trading",
        "description": "Кількість років, які організація учасник працює на ринку",
        "enum": [
          {
            "value": 0.05,
            "title": "До 3 років"
          },
          {
            "value": 0.1,
            "title": "Більше 3 років, менше 5 років"
          },
          {
            "value": 0.15,
            "title": "Більше 5 років"
          }
        ]
      }
    ],
    "milestones": [
      {
        "id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "title": "signingTheContract",
        "code": "prepayment",
        "type": "financing",
        "duration": {
          "days": 2,
          "type": "banking"
        },
        "sequenceNumber": 0,
        "percentage": 45.55
      },
      {
        "title": "deliveryOfGoods",
        "code": "postpayment",
        "type": "financing",
        "duration": {
          "days": 900,
          "type": "calendar"
        },
        "sequenceNumber": 0,
        "percentage": 54.45
      }
    ],
    "mainProcurementCategory": "services",
    "lots": [
      {
        "title": "lot title",
        "description": "lot description",
        "status": "active",
        "id": "9217965f43384438ac7af4b14e4fc52a",
        "date": "2023-10-10T01:00:00+03:00",
        "value": {
          "amount": 500.0,
          "currency": "UAH",
          "valueAddedTaxIncluded": true
        },
        "minimalStep": {
          "amount": 15.0,
          "currency": "UAH",
          "valueAddedTaxIncluded": true
        }
      }
    ]
  },
  "config": {
    "hasAuction": true,
    "hasAwardingOrder": true,
    "hasValueRestriction": true,
    "valueCurrencyEquality": true,
    "hasPrequalification": false,
    "minBidsNumber": 1,
    "hasPreSelectionAgreement": false,
    "hasTenderComplaints": false,
    "hasAwardComplaints": false,
    "hasCancellationComplaints": false,
    "restricted": false
  }
}

Response

HTTP/1.0 201 Created
Content-Type: application/json
Location: http://lb-api-sandbox.prozorro.gov.ua/api/2.5/tenders/fd4de4e2ac1044b38acaf4d7662bc817

{
  "data": {
    "mainProcurementCategory": "services",
    "title_en": "[TESTING] Cases with state awards",
    "title_ru": "[ТЕСТИРОВАНИЕ] футляры к государственным наградам",
    "title": "[ТЕСТУВАННЯ] футляри до державних нагород",
    "mode": "test",
    "status": "draft",
    "awardCriteria": "lowestCost",
    "value": {
      "amount": 500.0,
      "currency": "UAH",
      "valueAddedTaxIncluded": true
    },
    "minimalStep": {
      "amount": 15.0,
      "currency": "UAH",
      "valueAddedTaxIncluded": true
    },
    "tenderPeriod": {
      "startDate": "2023-10-17T00:00:00+02:00",
      "endDate": "2023-10-24T00:00:00+02:00"
    },
    "items": [
      {
        "id": "df827a0a87354ad59f985d4b31bbaf6c",
        "description": "футляри до державних нагород",
        "description_en": "Cases with state awards",
        "description_ru": "футляры к государственным наградам",
        "unit": {
          "name": "кілограм",
          "value": {
            "amount": 6.0,
            "currency": "UAH",
            "valueAddedTaxIncluded": true
          },
          "code": "KGM"
        },
        "quantity": 5.0,
        "classification": {
          "description": "Cartons",
          "scheme": "ДК021",
          "id": "44617100-9"
        },
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "17.21.1",
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ],
        "relatedLot": "9217965f43384438ac7af4b14e4fc52a"
      }
    ],
    "lots": [
      {
        "title": "lot title",
        "description": "lot description",
        "date": "2023-10-10T01:00:00+03:00",
        "id": "9217965f43384438ac7af4b14e4fc52a",
        "status": "active",
        "value": {
          "amount": 500.0,
          "currency": "UAH",
          "valueAddedTaxIncluded": true
        },
        "minimalStep": {
          "amount": 15.0,
          "currency": "UAH",
          "valueAddedTaxIncluded": true
        }
      }
    ],
    "features": [
      {
        "code": "OCDS-123454-AIR-INTAKE",
        "featureOf": "item",
        "relatedItem": "df827a0a87354ad59f985d4b31bbaf6c",
        "title": "Потужність всмоктування",
        "title_en": "Air Intake",
        "description": "Ефективна потужність всмоктування пилососа, в ватах (аероватах)",
        "enum": [
          {
            "value": 0.1,
            "title": "До 1000 Вт"
          },
          {
            "value": 0.15,
            "title": "Більше 1000 Вт"
          }
        ]
      },
      {
        "code": "OCDS-123454-YEARS",
        "featureOf": "tenderer",
        "title": "Років на ринку",
        "title_en": "Years trading",
        "description": "Кількість років, які організація учасник працює на ринку",
        "enum": [
          {
            "value": 0.05,
            "title": "До 3 років"
          },
          {
            "value": 0.1,
            "title": "Більше 3 років, менше 5 років"
          },
          {
            "value": 0.15,
            "title": "Більше 5 років"
          }
        ]
      }
    ],
    "milestones": [
      {
        "id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "title": "signingTheContract",
        "type": "financing",
        "code": "prepayment",
        "percentage": 45.55,
        "duration": {
          "days": 2,
          "type": "banking"
        },
        "sequenceNumber": 0
      },
      {
        "id": "7cd446edf5fc48fdbffcbb1d30c3b638",
        "title": "deliveryOfGoods",
        "type": "financing",
        "code": "postpayment",
        "percentage": 54.45,
        "duration": {
          "days": 900,
          "type": "calendar"
        },
        "sequenceNumber": 0
      }
    ],
    "procurementMethodType": "belowThreshold",
    "procuringEntity": {
      "name": "Державне управління справами",
      "identifier": {
        "scheme": "UA-EDR",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "address": {
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "locality": "м. Київ",
        "region": "м. Київ",
        "postalCode": "01220",
        "countryName": "Україна"
      },
      "contactPoint": {
        "name": "Державне управління справами",
        "telephone": "+0440000000"
      },
      "kind": "general"
    },
    "enquiryPeriod": {
      "endDate": "2023-10-17T00:00:00+02:00",
      "startDate": "2023-10-10T01:00:00+03:00",
      "clarificationsUntil": "2023-10-19T00:00:00+03:00"
    },
    "tenderID": "UA-2023-10-10-000002-a",
    "owner": "broker",
    "procurementMethod": "open",
    "submissionMethod": "electronicAuction",
    "date": "2023-10-10T01:00:00+03:00",
    "dateCreated": "2023-10-10T01:00:00+03:00",
    "dateModified": "2023-10-10T01:00:00+03:00",
    "id": "fd4de4e2ac1044b38acaf4d7662bc817"
  },
  "config": {
    "hasAuction": true,
    "hasAwardingOrder": true,
    "hasValueRestriction": true,
    "valueCurrencyEquality": true,
    "hasPrequalification": false,
    "minBidsNumber": 1,
    "hasPreSelectionAgreement": false,
    "hasTenderComplaints": false,
    "hasAwardComplaints": false,
    "hasCancellationComplaints": false,
    "restricted": false
  },
  "access": {
    "token": "ef719d3f89574a638a74a631043d6723",
    "transfer": "95855c6cd2d74bee9e8951fb9a95cc26"
  }
}

You can see the access with token in response. Its value can be used to modify objects further under “Owner role”.

Using token

You can pass access token in the following ways:

  1. acc_token URL query string parameter

  2. X-Access-Token HTTP request header

  3. access.token in the body of POST/PUT/PATCH request

See the example of the action with token passed as URL query string:

Request

PATCH /api/2.5/tenders/2f5e224866d0459cbaa950a15be70946?acc_token=f220033fc2004e90a9398defdea66c9f HTTP/1.0
Authorization: Bearer broker
Content-Type: application/json
Host: lb-api-sandbox.prozorro.gov.ua

{
  "data": {
    "tenderPeriod": {
      "startDate": "2023-10-17T00:00:00+02:00",
      "endDate": "2023-10-25T01:00:11+03:00"
    }
  }
}

Response

HTTP/1.0 200 OK
Content-Type: application/json

{
  "data": {
    "date": "2023-10-10T01:00:00+03:00",
    "dateModified": "2023-10-10T01:00:01+03:00",
    "dateCreated": "2023-10-10T01:00:00+03:00",
    "tenderID": "UA-2023-10-10-000001-a",
    "status": "active.enquiries",
    "owner": "broker",
    "title": "футляри до державних нагород",
    "mainProcurementCategory": "goods",
    "procurementMethod": "open",
    "submissionMethod": "electronicAuction",
    "awardCriteria": "lowestCost",
    "value": {
      "amount": 500.0,
      "currency": "UAH",
      "valueAddedTaxIncluded": true
    },
    "next_check": "2023-10-17T00:00:00+02:00",
    "minimalStep": {
      "amount": 15.0,
      "currency": "UAH",
      "valueAddedTaxIncluded": true
    },
    "tenderPeriod": {
      "startDate": "2023-10-17T00:00:00+02:00",
      "endDate": "2023-10-25T01:00:11+03:00"
    },
    "items": [
      {
        "id": "ffffffffffffffffffffffffffffffff",
        "description": "футляри до державних нагород",
        "description_en": "Cases with state awards",
        "description_ru": "футляры к государственным наградам",
        "unit": {
          "name": "кілограм",
          "value": {
            "amount": 6.0,
            "currency": "UAH",
            "valueAddedTaxIncluded": true
          },
          "code": "KGM"
        },
        "quantity": 5.0,
        "classification": {
          "description": "Cartons",
          "scheme": "ДК021",
          "id": "44617100-9"
        },
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "17.21.1",
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ],
        "relatedLot": "987404b67a4c4d888112d4e9755edefc"
      }
    ],
    "lots": [
      {
        "title": "lot title",
        "description": "lot description",
        "status": "active",
        "id": "987404b67a4c4d888112d4e9755edefc",
        "date": "2023-10-10T01:00:00+03:00",
        "value": {
          "amount": 500.0,
          "currency": "UAH",
          "valueAddedTaxIncluded": true
        },
        "minimalStep": {
          "amount": 15.0,
          "currency": "UAH",
          "valueAddedTaxIncluded": true
        }
      }
    ],
    "milestones": [
      {
        "id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "title": "signingTheContract",
        "type": "financing",
        "code": "prepayment",
        "percentage": 45.55,
        "duration": {
          "days": 2,
          "type": "banking"
        },
        "sequenceNumber": 0
      },
      {
        "id": "f16bf86d70dd4592a01e33f03b2babd0",
        "title": "deliveryOfGoods",
        "type": "financing",
        "code": "postpayment",
        "percentage": 54.45,
        "duration": {
          "days": 900,
          "type": "calendar"
        },
        "sequenceNumber": 0
      }
    ],
    "procurementMethodType": "belowThreshold",
    "procuringEntity": {
      "name": "Державне управління справами",
      "identifier": {
        "scheme": "UA-EDR",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "address": {
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "locality": "м. Київ",
        "region": "м. Київ",
        "postalCode": "01220",
        "countryName": "Україна"
      },
      "contactPoint": {
        "name": "Державне управління справами",
        "telephone": "+0440000000"
      },
      "kind": "general"
    },
    "enquiryPeriod": {
      "startDate": "2023-10-10T01:00:00+03:00",
      "clarificationsUntil": "2023-10-19T00:00:00+03:00",
      "endDate": "2023-10-17T00:00:00+02:00"
    },
    "id": "2f5e224866d0459cbaa950a15be70946"
  },
  "config": {
    "hasAuction": true,
    "hasAwardingOrder": true,
    "hasValueRestriction": true,
    "valueCurrencyEquality": true,
    "hasPrequalification": false,
    "minBidsNumber": 1,
    "hasPreSelectionAgreement": false,
    "hasTenderComplaints": false,
    "hasAwardComplaints": false,
    "hasCancellationComplaints": false,
    "restricted": false
  }
}