# Developer Changelog

RSS Feed, Atom Feed, JSON Feed

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:

Zaikio Apps

# Developer Changelog