Back to top

Printix partner api

The printix api for partners currently support the following operations:

  • Create a new tenant

  • Getting a single tenant including basic billing information

  • Canceling a tenants entire subscription

Prerequisites

Before using this api, you should have obtained a partnerId, a clientId and a client secret for each of the environments you wish to test against. Currently these are provided by printix in an out of band way (for example. email)

Authentication

HOST https://auth.printix.net

The api supports the oauth2 client credentials flow, meaning all clients should have a client id and client secret, which they exchange for a set of authentication and refresh tokens. The token endpoint is located at https://auth.printix.net/oauth/token for the production environment and https://auth.testenv.printix.net/oauth/token for a test environment. A Request for tokens is a simple form encoded POST request. Access tokens are expired after the amount of seconds mentioned in the “expires_in” response property. After expiration a new access token can be obtained by refreshing the token, by performing a similar request, with slightly different parameters

Request Tokens

Request tokens
POST/oauth/token

Example URI

POST /oauth/token
Request
HideShow

Replace the clientId and clientSecret variables in the request below:

Headers
Content-Type: application/x-www-form-urlencoded
Body
`grant_type=client_credentials&client_id={clientId}&client_secret={clientSecret}`
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "access_token": "5a8c4ec4-ff70-4f4c-b088-29a8cae38062",
  "refresh_token": "e6f05338-9d27-466b-afa8-0ce72945da7d",
  "expires_in": 599
}

Refresh Tokens
POST/oauth/token

Example URI

POST /oauth/token
Request
HideShow

Replace the clientId and refreshToken variables in the request below:

Headers
Content-Type: application/x-www-form-urlencoded
Body
`grant_type=refresh_token&client_id={clientId}&refresh_token={refreshToken}`
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "access_token": "5a8c4ec4-ff70-4f4c-b088-29a8cae38062",
  "refresh_token": "e6f05338-9d27-466b-afa8-0ce72945da7d",
  "expires_in": 599
}

Tenants

HOST https://api.printix.net

Tenants

List Tenants
GET/public/partners/{partnerId}/tenants

Fetches a list of previously created tenants.

Example URI

GET /public/partners/00000000-1111--22222-123456789abc/tenants
URI Parameters
HideShow
partnerId
uuid (required) Example: 00000000-1111--22222-123456789abc
Response  200
HideShow
Headers
Content-Type: application/hal+json
Body
{
  "_links": {
    "self": {
      "href": "https://api.printix.net/public/partners/00000000-1111--22222-123456789abc/tenants"
    }
  },
  "tenants": [
    {
      "tenant_name": "Acme Co.",
      "tenant_domain": "acme.printix.net",
      "billing_info": {
        "_links": {
          "self": {
            "href": "https://api.printix.net/public/partners/00000000-1111--22222-123456789abc/tenants/99999999-8888-7777-6666-fedcba987654/billing-info"
          }
        },
        "current_user_licenses": 1,
        "current_billing_period": {
          "period_start": "2017-11-24T16:15:10.480Z",
          "period_end": "2017-12-24T16:15:10.480Z",
          "printing_users": 1,
          "user_licenses": 1
        },
        "previous_billing_period": {
          "period_start": "2017-11-24T16:15:10.480Z",
          "period_end": "2017-12-24T16:15:10.480Z",
          "printing_users": 1,
          "user_licenses": 1
        }
      },
      "_links": {
        "self": {
          "href": "https://api.printix.net/public/partners/00000000-1111--22222-123456789abc/tenants/99999999-8888-7777-6666-fedcba987654"
        },
        "billing_info": {
          "href": "https://api.printix.net/public/partners/00000000-1111--22222-123456789abc/tenants/99999999-8888-7777-6666-fedcba987654/billing-info"
        }
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "_links": {
      "type": "object",
      "properties": {
        "self": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string"
            }
          }
        }
      }
    },
    "tenants": {
      "type": "array"
    }
  }
}

Create new tenant
POST/public/partners/{partnerId}/tenants

To create a new tenant, perform a POST request to the tenants endpoint The json payload must include at least a tenant_name and a tenant_domain

  • tenant_name: The actual name of the tenant to create. A freeform string that can contain capital letters spaces and special characters. Max size 100 characters

  • tenant_domain: should be a (sub)domain name, it will be used to generate the Printix Home of the customer, where they can manage their solution and release documents. This value should include only lowercase alphanumeric characters and dashes. So, for example, for a customer named Acme C/O a logical tenant_domain would be acme, and the printix administrator for the customer would then be available on https://acme.printix.net

Optionally a client can also include

  • initial_user: Useful if the client should be granted access to manage their own printix solution. If this is not supplied, no users will be created on the tenant, and the partner would need to manually invite the users. If the user has never signed into printix before, they will need to reset their password the first time they access either the printix administrator or the user app. initial user has the following properties:
    • email: The email of the user. This will also be their login name.
    • name: The name of the user
    • create_as_admin: should the user be created as a printix administrator, either true or false, the default is false

Example URI

POST /public/partners/00000000-1111--22222-123456789abc/tenants
URI Parameters
HideShow
partnerId
uuid (required) Example: 00000000-1111--22222-123456789abc
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer {access_token}
Body
{
  "tenant_name": "Acme Co.",
  "tenant_domain": "acme.printix.net",
  "initial_user": {
    "email": "Hello, world!",
    "name": "Hello, world!",
    "create_as_admin": true
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "tenant_name": {
      "type": "string"
    },
    "tenant_domain": {
      "type": "string"
    },
    "initial_user": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "create_as_admin": {
          "type": "boolean"
        }
      }
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/hal+json
Body
{
  "tenant_name": "Acme Co.",
  "tenant_domain": "acme.printix.net",
  "billing_info": {
    "_links": {
      "self": {
        "href": "https://api.printix.net/public/partners/00000000-1111--22222-123456789abc/tenants/99999999-8888-7777-6666-fedcba987654/billing-info"
      }
    },
    "current_user_licenses": 1,
    "current_billing_period": {
      "period_start": "2017-11-24T16:15:10.480Z",
      "period_end": "2017-12-24T16:15:10.480Z",
      "printing_users": 1,
      "user_licenses": 1
    },
    "previous_billing_period": {
      "period_start": "2017-11-24T16:15:10.480Z",
      "period_end": "2017-12-24T16:15:10.480Z",
      "printing_users": 1,
      "user_licenses": 1
    }
  },
  "_links": {
    "self": {
      "href": "https://api.printix.net/public/partners/00000000-1111--22222-123456789abc/tenants/99999999-8888-7777-6666-fedcba987654"
    },
    "billing_info": {
      "href": "https://api.printix.net/public/partners/00000000-1111--22222-123456789abc/tenants/99999999-8888-7777-6666-fedcba987654/billing-info"
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "tenant_name": {
      "type": "string"
    },
    "tenant_domain": {
      "type": "string"
    },
    "billing_info": {
      "type": "object",
      "properties": {
        "_links": {
          "type": "object",
          "properties": {
            "self": {
              "type": "object",
              "properties": {
                "href": {
                  "type": "string"
                }
              }
            }
          }
        },
        "current_user_licenses": {
          "type": "number"
        },
        "current_billing_period": {
          "type": "object",
          "properties": {
            "period_start": {
              "type": "string"
            },
            "period_end": {
              "type": "string"
            },
            "printing_users": {
              "type": "number"
            },
            "user_licenses": {
              "type": "number"
            }
          }
        },
        "previous_billing_period": {
          "type": "object",
          "properties": {
            "period_start": {
              "type": "string"
            },
            "period_end": {
              "type": "string"
            },
            "printing_users": {
              "type": "number"
            },
            "user_licenses": {
              "type": "number"
            }
          }
        }
      }
    },
    "_links": {
      "type": "object",
      "properties": {
        "self": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string"
            }
          }
        },
        "billing_info": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Interacting with a single tenant

Fetching a single tenant
GET/public/partners/{partnerId}/tenants/{tenantId}

Viewing a single tenant is done by making a get request to the tenant url

Example URI

GET /public/partners/00000000-1111--22222-123456789abc/tenants/99999999-8888-7777-6666-fedcba987654
URI Parameters
HideShow
partnerId
uuid (required) Example: 00000000-1111--22222-123456789abc
tenantId
uuid (required) Example: 99999999-8888-7777-6666-fedcba987654
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer {access_token}
Response  200
HideShow
Headers
Content-Type: application/hal+json
Body
{
  "tenant_name": "Acme Co.",
  "tenant_domain": "acme.printix.net",
  "billing_info": {
    "_links": {
      "self": {
        "href": "https://api.printix.net/public/partners/00000000-1111--22222-123456789abc/tenants/99999999-8888-7777-6666-fedcba987654/billing-info"
      }
    },
    "current_user_licenses": 1,
    "current_billing_period": {
      "period_start": "2017-11-24T16:15:10.480Z",
      "period_end": "2017-12-24T16:15:10.480Z",
      "printing_users": 1,
      "user_licenses": 1
    },
    "previous_billing_period": {
      "period_start": "2017-11-24T16:15:10.480Z",
      "period_end": "2017-12-24T16:15:10.480Z",
      "printing_users": 1,
      "user_licenses": 1
    }
  },
  "_links": {
    "self": {
      "href": "https://api.printix.net/public/partners/00000000-1111--22222-123456789abc/tenants/99999999-8888-7777-6666-fedcba987654"
    },
    "billing_info": {
      "href": "https://api.printix.net/public/partners/00000000-1111--22222-123456789abc/tenants/99999999-8888-7777-6666-fedcba987654/billing-info"
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "tenant_name": {
      "type": "string"
    },
    "tenant_domain": {
      "type": "string"
    },
    "billing_info": {
      "type": "object",
      "properties": {
        "_links": {
          "type": "object",
          "properties": {
            "self": {
              "type": "object",
              "properties": {
                "href": {
                  "type": "string"
                }
              }
            }
          }
        },
        "current_user_licenses": {
          "type": "number"
        },
        "current_billing_period": {
          "type": "object",
          "properties": {
            "period_start": {
              "type": "string"
            },
            "period_end": {
              "type": "string"
            },
            "printing_users": {
              "type": "number"
            },
            "user_licenses": {
              "type": "number"
            }
          }
        },
        "previous_billing_period": {
          "type": "object",
          "properties": {
            "period_start": {
              "type": "string"
            },
            "period_end": {
              "type": "string"
            },
            "printing_users": {
              "type": "number"
            },
            "user_licenses": {
              "type": "number"
            }
          }
        }
      }
    },
    "_links": {
      "type": "object",
      "properties": {
        "self": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string"
            }
          }
        },
        "billing_info": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

Billing information

Get billing information
GET/public/partners/{partnerId}/tenants/{tenantId}/billing-info

Example URI

GET /public/partners/00000000-1111--22222-123456789abc/tenants/99999999-8888-7777-6666-fedcba987654/billing-info
URI Parameters
HideShow
partnerId
uuid (required) Example: 00000000-1111--22222-123456789abc
tenantId
uuid (required) Example: 99999999-8888-7777-6666-fedcba987654
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer {access_token}
Response  200
HideShow
Headers
Content-Type: application/hal+json
Body
{
  "_links": {
    "self": {
      "href": "https://api.printix.net/public/partners/00000000-1111--22222-123456789abc/tenants/99999999-8888-7777-6666-fedcba987654/billing-info"
    }
  },
  "current_user_licenses": 1,
  "current_billing_period": {
    "period_start": "2017-11-24T16:15:10.480Z",
    "period_end": "2017-12-24T16:15:10.480Z",
    "printing_users": 1,
    "user_licenses": 1
  },
  "previous_billing_period": {
    "period_start": "2017-11-24T16:15:10.480Z",
    "period_end": "2017-12-24T16:15:10.480Z",
    "printing_users": 1,
    "user_licenses": 1
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "_links": {
      "type": "object",
      "properties": {
        "self": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string"
            }
          }
        }
      }
    },
    "current_user_licenses": {
      "type": "number"
    },
    "current_billing_period": {
      "type": "object",
      "properties": {
        "period_start": {
          "type": "string"
        },
        "period_end": {
          "type": "string"
        },
        "printing_users": {
          "type": "number"
        },
        "user_licenses": {
          "type": "number"
        }
      }
    },
    "previous_billing_period": {
      "type": "object",
      "properties": {
        "period_start": {
          "type": "string"
        },
        "period_end": {
          "type": "string"
        },
        "printing_users": {
          "type": "number"
        },
        "user_licenses": {
          "type": "number"
        }
      }
    }
  }
}

Generated by aglio on 11 Nov 2021