Skip to content

Corksy API (1.2.0)

API for retrieving orders, customers, inventory, wine-club data, and products.

Authentication

This API uses a two-step authentication process:

Step 1: Generate API Key

First, generate your API key from the Admin Settings API page:

  • Go to: https://admin.corksy.io/settings/apiaccess
  • Create a new API key for your application

Step 2: Obtain Bearer Token

Use your API key to obtain a bearer token by making a POST request to the authentication endpoint:

Production:

curl --location 'https://connect-api.corksy.io/v1/auth/public/login' \
--header 'Content-Type: application/json' \
--data '{
    "apiKey": "your-api-key-here"
}'

Staging:

curl --location 'https://staging.corksy.io/connect-api/v1/v1/auth/public/login' \
--header 'Content-Type: application/json' \
--data '{
    "apiKey": "your-api-key-here"
}'

Response:

{
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 1800000
}

Step 3: Use Bearer Token

Use the accessToken from the response as a Bearer token in the Authorization header for all subsequent API requests:

Example Requests:

Get Orders:

curl --location 'https://connect-api.corksy.io/v1/orders?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Get Customers:

curl --location 'https://connect-api.corksy.io/v1/customers' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Get Inventory:

curl --location 'https://connect-api.corksy.io/v1/inventory' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Get Wine Clubs:

curl --location 'https://connect-api.corksy.io/v1/wine-clubs' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Get Wine Club Members:

curl --location 'https://connect-api.corksy.io/v1/wine-club-members' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Get Products:

curl --location 'https://connect-api.corksy.io/v1/products?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Note: The bearer token expires after 30 minutes (1,800,000 microseconds). You'll need to obtain a new token when it expires.

Pagination

All list endpoints support pagination to handle large datasets efficiently. The API uses offset-based pagination with the following parameters:

Pagination Parameters

  • offset (optional): Number of records to skip. Default: 0
  • pageSize (optional): Number of records to return per page. Default: 1000, Maximum: 1000

Pagination Response

Each paginated response includes a pagination object with the following information:

{
  "data": [...],
  "pagination": {
    "current_offset": 0,
    "page_size": 50,
    "total_records": 1250,
    "total_pages": 25,
    "current_page": 1,
    "pages_remaining": 24,
    "has_next_page": true,
    "has_previous_page": false
  }
}

Pagination Examples

First Page (Default):

curl --location 'https://connect-api.corksy.io/v1/orders?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31' \
--header 'Authorization: Bearer YOUR_TOKEN'

Second Page (50 records per page):

curl --location 'https://connect-api.corksy.io/v1/orders?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31&offset=50&pageSize=50' \
--header 'Authorization: Bearer YOUR_TOKEN'

Custom Page Size:

curl --location 'https://connect-api.corksy.io/v1/orders?modifiedFromDate=2025-05-01&modifiedToDate=2025-05-31&pageSize=100' \
--header 'Authorization: Bearer YOUR_TOKEN'

Best Practices

  1. Start with the first page (no parameters or offset=0)
  2. Use has_next_page to determine if more pages exist
  3. Increment offset by page_size to get the next page
  4. Choose appropriate page_size based on your needs.
  5. Handle rate limits - each page request counts toward your rate limit
Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Staging Environment
https://staging.corksy.io/connect-api/v1/
Production Environment
https://connect-api.corksy.io/

Authentication

Endpoints related to authentication and authorization

Operations

Authenticate with API key to obtain bearer token

Request

Authenticate using your API key to obtain a JWT bearer token for accessing protected endpoints.

Rate Limit: 10 requests / minute

Note: The returned token expires after 30 minutes. You'll need to call this endpoint again to get a new token.

Bodyapplication/jsonrequired
apiKeystringrequired

Your API key obtained from the Admin Settings API page

Example: "your-api-key-here"
curl -i -X POST \
  https://staging.corksy.io/connect-api/v1/v1/auth/public/login \
  -H 'Content-Type: application/json' \
  -d '{
    "apiKey": "your-api-key-here"
  }'

Responses

Authentication successful

Bodyapplication/json
accessTokenstringrequired

JWT bearer token for API access

Example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
expiresInintegerrequired

Token expiration time in microseconds

Example: 1800000
Response
application/json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "expiresIn": 1800000
}

Orders

Endpoints related to orders

Operations

Customers

Endpoints related to customers

Operations

Inventory

Endpoints related to inventory

Operations

Wine Clubs

Endpoints related to wine clubs

Operations

Wine Club Members

Endpoints related to wine-club members

Operations

Products

Endpoints related to products

Operations