Developer Changelog

RSS Feed, Atom Feed, JSON Feed

• Mission Control Data Platform

  July 25, 2023

  [IMPORTANT] Mission Control and Data Platform split

  Action required Update

  As we've learned more about how we think about the world of print data, we've decided to split what used to be known as "Mission Control" into two concepts. "Mission Control" will specialise as an App on the Zaikio platform that offers an industry leading set of List-based functionality, advanced production planning tools and a great shop floor data collection experience. Now for the fun bit. We're delighted to promote our modeling of the print ecosystem to the heart of our product offering. As we've spoken to our Partner Community, we've understood that print job data isn't part of what we do, it's the very core of what we do. We're moving the majority of the former "Mission Control" API into the "Zaikio" namespace to better reflect its importance to us as the essence of our business. All Zaikio Organizations will now automatically have access to the data platform, and in time this will be charged on a metered per-Job basis with packages available at common usage bands. More details on this will follow in future, and there will be a free tier. The good news is that there are no immediate changes to the data model, and we'll operate a long crossover period to make switching simple. TLDR;

  • No immediate changes needed - No changes in the data model - All non-List API endpoints are available at their new home:
    • sandbox: https://data.sandbox.zaikio.com
    • live: https://data.zaikio.com
  • All mission_control.* OAuth scopes are now also available as zaikio.* scopes - All mission_control.* events are also available as zaikio.* events - All existing endpoints, scopes and events will run for the next months to allow for graceful migrations - List based activities continue to use the existing mission_control endpoints, scopes and events

  What do I need to do?

  OAuth Scopes

  All former mission_control.* scopes are now available as zaikio.* scopes. The existing scopes will still work without any changes. We would request that over time you look to migrate to the new scopes, but we will advertise our hard deadlines for this in future.

  Events

  All former mission_control.* events are now available as zaikio.* events. We are sending both versions of the event for now but in time we will migrate remaining subscriptions to the new zaikio namespace. Again, we will advertise this transition date well before it happens #### URLs Please start using the new data. URLs to access our API. We will shortly be upgrading the infrastructure that our data platform runs on, but the performance advantages will require you to migrate to the new URL... In time, we will switch off the old ones, and again this will be publicised well in advance. How's that for a carrot-or-stick situation? Please reach out to our partner success team directly or on the community slack if you've got any questions or notice any strange behaviours. We run all of our own products on the platform and are confident this is stable, but we're standing by to support you all.

  ---

• Zaikio OAuth API Zaikio Loom

  June 1, 2023

  [DEPRECATING] The directory app name

  Action required Update

  As we are upgrading and merging some of our APIs we are deprecating the directory app name. Instead the main app everybody is connected with will be called zaikio. Currently you can use both app names for requesting OAuth Scopes or receiving Loom events. You can see app specific warnings and instructions in Zaikio's Developer area of your vendor organization.

  What do I need to do?

  OAuth Scopes

  Make sure that all OAuth scopes that you pass as scopes and are prefixed with directory. in the various OAuth flows are prefixed now with zaikio.. For example directory.person.r becomes zaikio.person.r.

  Loom Events

  Make sure that you are listening to zaikio. loom events instead of directory. loom events. For example directory.connection_established becomes zaikio.connection_established. We recommend to support receiving events with both app names. After you are able to receive zaikio. events you can switch to only listen to those by pressing "Receive zaikio. events" in Zaikio's Developer area within "Subscribed Events" section.

  What's next?

  • On October 4th 2023 we will drop the support for requested directory. OAuth scopes in every OAuth Flow. This means those scopes will not be included in the access token in case there were requested. We will also stop sending directory. loom events and instead send only zaikio. events. - If you have any questions or need help, please contact us in the Zaikio Slack Community Workspace.

  ---

• Zaikio OAuth API

  August 9, 2022

  Removing refresh_token in client_credentials flow

  Action required Update

  If you are using the grant_type: client_credentials to fetch access token and you are currently using the refresh_token from that response to fetch further access tokens, this is a breaking change.

  In order to improve regular security measures we want to follow OAuth RFC recommendations. This includes not responding with a refresh_token in the Client Credentials Grant flow (see https://www.rfc-editor.org/rfc/rfc6749#section-4.4.3).

  What do I need to do?

  If you only use the refresh token as intended (e.g. through redirect grant or device grant flow), there is nothing you need to do.

  If you use the refresh_token from the Client Credentials Grant, you will need to re-fetch an access token by performing another Client Credentials Grant instead of using a refresh_token.

  What's next?

  • On TBA (paused) we will drop the refresh_token from the client_credentials responses.

  ---

• Zaikio OAuth API

  May 9, 2022

  Rotating JWKs for regular security measures

  Action required Update

  If you are verifying Zaikio signed JSON Web Tokens (JWTs) as described in our JWT Validation guide, please read this announcement. If you are not offering an API that accepts Zaikio's JWTs (e.g. you are consuming the Procurement API), you do not need to take any action.

  In order to improve regular security measures we will start rotating keys that are used to sign Zaikio's JWTs.

  We will do future rotations unannounced and randomly, so please make sure you are following our instructions.

  What do I need to do?

  1. Make sure you are not hardcoding Zaikio's public keys from /api/v1/jwt_public_keys. Instead read those keys directly from our API or cache them for an hour maximum.
  2. Make sure that your JWT library accepts multiple keys and that you try all published keys. Have a look in our JWT Validation guide for some implementation examples. We will always have some older keys, that have still JWTs that are signed with those (e.g. a personal access token is valid for 1 year), which is why you always have to support all keys, that you can find in /api/v1/jwt_public_keys. Our new public key is already available but not used yet to sign JWTs.

  What's next?

  • On Monday May 9th, 2022 around 10:00 AM CEST we will sign new JWTs with our new JWK on sandbox.
  • On Wednesday May 11th, 2022 around 10:00 AM CEST we will sign new JWTs with our new JWK on production.

  ---

• Zaikio OAuth API

  April 16, 2021

  BREAKING: OAuth Redirect Flow redirect with errors

  Action required Update

  In the OAuth redirect flow, the client typically has the ability to process error messages if they are returned as a query parameter to the redirect URL (see OAuth RFC: https://tools.ietf.org/html/rfc6749#section-4.1.2.1).
  
  Until today this was unfortunately not possible and error messages were displayed directly in Zaikio. With this change it is possible to handle the error by yourself.
  
  In case of an error, the redirect URL will be redirected in the following way: {REDIRECT_URL}?error={error_id}&error_description={optional description} Possible Errors:

  • invalid_request: Usually related to invalid PKCE
  • access_denied: The user cancelled the redirect flow intentionally
  • invalid_scope: The scopes provided were invalid, the error description contains details about the invalid scope (see Scopes)

  This change affects the Zaikio OAuth redirect flow. On June 15, 2021, this change will be rolled out to everyone on a mandatory basis. Until then, the new logic can already be used via an optional parameter (https://hub.zaikio.com/oauth/authorize/?redirect_with_error=1&client_id=...) to enable a smooth transition. For all new apps created from now on, the new logic already applies. Many OAuth client libraries will probably already handle this behavior, so we recommend just trying the parameter.

  ---

• Procurement Consumers API Procurement Suppliers API

  February 4, 2021

  Changes to Variant paper_weight_unit value

  Action required Update

  We are going to change the Variant property paper_weight_unit on 2021-03-04:

  • basis weight will no longer be supported as a value - Any existing fields set as grammage will be converted to the equivalent metric unit gsm - gsm will be the only accepted value when creating or updating Variants from this date If you are creating or updating Variants now, please set paper_weight_unit to gsm and be prepared to handle this value in any API response which includes Variant information.

  ---

• Zaikio Hub API

  February 1, 2021

  BREAKING: /connections and /subscriptions

  Action required Update

  The API endpoints GET /connections AND GET /subscriptions will introduce pagination. The reponse will include following Headers:

  • Link Links to previous and next pages, in the format described in RFC 8288 The relations first, prev, next and last can be present.
  • Current-Page The current page of the paginated response (starting at 1)
  • Total-Count The total number of items in this collection
  • Total-Pages The total number of pages for the current page size in this collection
    
    and following query parameters will be accepted:
    
  • page The page of the current collection that shall be returned (starting at 1)
  • per_page The maximum number of items included in the response, ie., the page size (100 by default)
    
    Furthermore it is also possible to provide a filter on GET /subscriptions:
  • filters[subscriber_id] e.g. Organization-d2e78ba7-5cfc-4359-9d8a-43ce0fa3a795
    
    and on GET /connections:
  • filters[connectable_id] e.g. Organization-d2e78ba7-5cfc-4359-9d8a-43ce0fa3a795
    
    Further Reading: Zaikio Hub API Reference to be released

  ---

• Procurement API

  January 27, 2021

  Links for nested SKUs on OrderLineItems will return null if the SKU has been deleted

  Update

  All endpoints that retrieve OrderLineItems with nested SKU data, will now return null for the links attribute of the SKU if the SKU has been deleted. The following endpoints are affected:
  
  - GET /orders
  - POST /orders
  - GET /orders/{order_id}
  - PATCH /orders/{order_id}
  - GET /orders/{order_id}/order_line_items
  - POST /orders/{order_id}/order_line_items
  - GET /order_line_items/{order_line_item_id}
  - PATCH /order_line_items/{order_line_item_id}
  

  ---

• Zaikio Hub API

  June 9, 2020

  DEPRECATED: /blacklisted_access_tokens

  Action required Update

  The API endpoints GET/POST /blacklisted_access_tokens is deprecated and got renamed to GET/POST /revoked_access_tokens. The attribute also got renamed to revoked_token_ids. The old API endpoints get deleted on the 1st of August.
  
  Further Reading: Zaikio Hub API Reference Revoked Access Tokens

  ---

• Zaikio Hub API

  March 16, 2020

  DEPRECATED: site_id in machines

  Action required Update

  The site is now part of machine ownership and should therefore be set together via machines/{machine_id}/ownership. That is why we now also offer a PATCH machines/{machine_id}/ownership so that the site ID can be changed.
  
  We will allow the site to be set in the machine until April 6, 2020. After that, setting the site will only be possible in the ownership.
  
  Further Reading: Zaikio Hub API Reference POST /machines/{machine_id}/ownership

  ---

• Zaikio Hub API

  March 12, 2020

  OAuth Credentials: Name and description

  New Update

  From now on, a non-public description can be added when creating or modifying OAuth credentials.
  
  In addition, a name with a maximum of 4 characters can optionally be added. This extends the audience (aud) of the JSON Web token. If the audience was my_app it can now also be my_app/{credentials_name} if a name is given. The name must be unique within your app. However, other apps may have the same name, so you need to check the app name as well.
  
  If you want to test your JWT, try our interactive JWT Verifier.

  ---

• Zaikio Hub API

  March 10, 2020

  In Redirect Flow and Device Flow an organization can be pre-selected

  New Update

  It is now allowed to pass an Organization ID in Redirect Flow and Device Flow, so the user does not have to select the organization in Zaikio.
  
  The organizational ID is then passed as a scope as in Client Credentials Flow. For example:
  Org/5345a2a-8786-5b46-a1e2-516658fde390.directory.organization.r
  
  It is only possible to set organizations where the current user is also the admin.

  ---

• Zaikio Hub API

  March 5, 2020

  API returns if email of person was confirmed

  New Update

  We already return the email in our API. In addition, there is a new attribute email_confirmed, which indicates whether the user has confirmed the given email. No emails should be sent or the identity should be confirmed based on an email as long as this email has not also been confirmed.

  ---

• Zaikio Hub API

  February 27, 2020

  Person Bearer: Restrictions on sites and machines

  Action required Update

  If you use an Access Token with Person Bearer, it is no longer possible to perform every action for security reasons. If the bearer is a normal member of an organization (not an admin) then it is no longer possible:
  
  - POST /machines​/{machine_id}​/machine_ownership
  - POST /sites
  - PATCH /sites/{site_id}
  
  If these requests now fail a 403 Forbidden is returned. Every other endpoint works as before. If an admin is the bearer, there is no change.

  ---

• Zaikio Hub API

  February 25, 2020

  First name can be null

  Action required Update

  Since many countries do not have first names, we are now making this field optional for all members. This means in the API response the first_name can be null. We recommend to always use the full_name to display a name.

  ---

• Zaikio Hub API

  February 12, 2020

  New: Create Organizations

  New

  It is now possible to create new organizations with a Person Access Token. For this purpose the new scope directory.organizations.w is required. The current user will then automatically become the owner of the organization.
  
  In addition, the app that issued the token will connect directly with desired OAuth Scopes and Event Subscriptions from the directory. This means that after creation you can directly request an Organization Access Token via the Client Credentials Flow.
  
  Further Reading: Zaikio Hub API Reference POST /person/organizations

  ---

• Zaikio Hub API

  February 12, 2020

  New: Revoke OAuth Access Tokens

  New

  You can now use our new security feature to revoke OAuth Access Tokens. If an access token is accidentally leaked, you should revoke it immediately.
  
  Further Reading: Zaikio Hub API Reference POST /blacklisted_access_tokens

  ---

• Hub Events

  February 12, 2020

  New: Loom events for member lifecycle events

  New

  We now offer 3 new Loom events. Furthermore it is now possible to access a single membership via the API using the UUID.:
  directory.member_joined
directory.member_roles_updated
directory.member_left
  
  Further Reading: Receiving Events with Loom, Reference of Hub Events

  ---

• Zaikio Hub API

  February 12, 2020

  New: sites write OAuth Scope and endpoint

  New Update

  You can now also create and update sites using the Zaikio Hub API. To do this, you need one of the new OAuth scopes such as directory.sites.w or directory.sites.rw.
  
  Further Reading: Zaikio Hub API Reference

  ---

• Zaikio Hub API

  February 10, 2020

  New: sites read OAuth Scope

  New Update

  The directory now offers a new OAuth Scope called directory.sites.r which can only read information from the sites.
  
  A new endpoint has also been added to return information of a single page (/api/v1/sites/{site_id}).
  
  Also, addresses can now be retrieved for each site if they have been added.
  
  Furthermore, the site_id is now also returned for the machines, if a site has been assigned to the machine.
  
  Further Reading: Zaikio Hub API Reference

  ---

• Zaikio Hub API

  February 7, 2020

  Users can not connect to foreign and unreviewed Apps in production

  Action required Update

  It is no longer allowed for users to connect to any App in production environment. As the zaikio platform we have to make sure that all apps comply with our security standards and that malicious apps do not connect.
  
  However, organizations and members can connect to self-created apps at any time (i.e. the vendor is the own organization). In addition, all apps can connect in the sandbox environment, since no sensitive data is stored there.
  
  In order for your app to be available in production, you have to bring your app into the review process (this can be done on the detail page of your app). In order for us to activate the app, however, it should be usable (i.e. you provide a redirect flow and/or an API with appropriate documentation). For this purpose we will contact you.

  ---

• Zaikio Hub API

  February 5, 2020

  Person: new attribute unit_system and locale en-US

  New Update

  The person endpoint now returns a new attribute named unit_system. This can be either metric or imperial. Each person can manage this setting themselves.
  
  There is also a new locale that the user can select: en-US. This new locale can be used to display different date formats, for example.
  
  Further Reading: Zaikio Hub API Reference

  ---

• Zaikio Hub API

  February 3, 2020

  Country code and currency for all organization and person responses

  New

  From now on, all responses from organisations and persons will contain a country_code and a currency attribute, the currency attribute being derived from the country code. The attributes can be null if the country was not provided by the organisation or person.
  
  Further Reading: Zaikio Hub API Reference

  ---

• Hub Events

  January 30, 2020

  New Connection Lifecycle Loom Events

  New

  With our new Loom Events it is now possible to be notified when a connection has been established or revoked. In addition, we now send a new event when an access token is revoked. It is recommended to use this event for security reasons.
  
  Further Reading: Receiving Events with Loom, Reference of Hub Events

  ---

• Zaikio Hub API

  January 30, 2020

  JWT Issuer (iss) changes from CP to ZAI

  Action required Update

  JSON web tokens created by the Zaikio Hub are now issued by ZAI, before it was CP. Since you most likely do not work with this attribute, nothing needs to be done.

  ---

• Loom API

  January 30, 2020

  Loom API migrated to loom.zaikio.com

  Action required Update

  The Loom event changed its domain to loom.zaikio.com (respectively loom.sandbox.zaikio.com for the sandbox environment).

  ---

• Zaikio Hub API

  January 28, 2020

  New connections endpoint and connected attribute

  New

  It is now possible to retrieve all connections for an app. To do this, a GET request must be made to /api/v1/connections or /api/v1/connections/Person-abc-def-ghi. This request must be authenticated by Basic Auth (the Client Id must be the username and the Client Secret the password, this is only possible if the credentials are confidential).
  
  Additionally, there is the connected attribute in all API replies sent. So it is for example possible to see via a GET /api/v1/person request which organizations of the person are already connected to the app that requested the access token. Please check the Zaikio Hub API Reference for more details.

  ---

• Zaikio Hub API

  January 27, 2020

  Event Webhook URL is now managed in the App configuration

  Action required Update

  In the past each Event Subscription had to define its own Webhook URL. Now each App needs to define only one Webhook URL in its configuration and this Webhook URL will be used to deliver all Events.
  
  Note: At the moment this Webhook URL is only required when you want to add an Event Subscription to your App. In the future there will be events types that sent to all Apps and Apps will not need to explicitly subscribe to these event types. Therefore we will need to require all Apps having a Webhook URL soon.

  ---

• Zaikio Hub API

  January 21, 2020

  Client Credentials Flow: The bearer must first grant access to the app

  Action required Update

  Requested scopes by the Client Credentials Flow must be granted beforehand, otherwise the scope error ungranted_scope (see scope errors) will be returned.
  
  This means that the person or organization must have successfully accepted the scopes in advance through a Redirect Flow (or through the Device Flow) for this app.
  
  This authorization can also be done later directly through the Zaikio Hub App (via Connections), if the App has been approved by the Zaikio Team. If you want to participate, please contact us directly.

  ---

• Zaikio Hub API

  January 16, 2020

  OAuth Scopes in directory are limited to certain bearer types

  Action required Update

  As documented in the Zaikio Hub API Reference these directory some scopes will only be available for certain Bearer types (otherwise an unavailable_scope_for_bearer_type error will be returned):
  
  directory.person.r => only for Person
directory.organization.r, directory.organization_members.r => only for Organization
  
  This does not change the functionality, as these scopes will not work with another Bearer type.

  ---

• Zaikio Hub API

  January 15, 2020

  Accept only desired scopes

  Action required Update

  Requested scopes must be created as Desired Scopes in the directory app, otherwise a new scope error scope_is_not_included_in_desired_scopes (see scope errors) is returned.

  ---

• Zaikio Hub API

  January 14, 2020

  Delegations only usable for confidential clients

  Action required Update

  The Delegation access flow only accepts access tokens to delegate that were created with OAuth confidential credentials. If you try to access this endpoint without an access token that was created with OAuth confidential credentials, it will return from now on a 403 (Forbidden).

  ---

• Loom API

  January 9, 2020

  Events require valid subject

  Action required Update

  From now on it is required that the JSON body includes a valid subject when posting events to the Loom API. The `subject identifies the Person or Organization in which context the event was triggered. The event will only be delivered to Apps that are connected to the subject and that have granted access to the specific event type. Read more

  ---

• Zaikio Hub API

  January 7, 2020

  On behalf of Person for Client Credentials Flow released

  New

  The Client Credentials Flow provides now the option of issuing a token for an organisation, which also references a person and specifies their roles in the context of this organisation in the JWT. Read more

  ---

• Zaikio Hub API

  December 18, 2019

  Private apps take effect

  Action required Update

  From now Private apps can only be accessed by the organisation that created the app, or any of it's members. If you want everybody to be able to access your app please switch to External in the app's details pane.

  ---

• Zaikio Hub API

  December 18, 2019

  Scope Restriction

  Action required Update

  Scopes for all Zaikio Hub API endpoints will now take effect. If you don't send the right scopes yet, please check the Zaikio Hub API Reference. You find a list of scopes and bearers that are required for each endpoint.

  ---

• Zaikio Hub API

  December 16, 2019

  Roles endpoint

  New

  You can now access the public endpoint GET /roles to view all roles. Please check the Zaikio Hub API Reference for more details.

  ---

• Zaikio Hub API

  December 1, 2019

  Organization endpoint

  New

  You can now access GET /organization to view an organization's name and other meta data. Please check the Zaikio Hub API Reference for more details.

  ---

Filter by:

Filter by: