# Developer Changelog
RSS Feed, Atom Feed, JSON Feed
- Zaikio OAuth API
Removing refresh_token in client_credentials flow
Action required UpdateIf you are using the
grant_type: client_credentials
to fetch access token and you are currently using therefresh_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 arefresh_token
.What's next?
- On TBA (paused) we will drop the
refresh_token
from theclient_credentials
responses.
- On TBA (paused) we will drop the
- Zaikio OAuth API
Rotating JWKs for regular security measures
Action required UpdateIf 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?
- 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. - 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.
- Make sure you are not hardcoding Zaikio's public keys from
- Zaikio OAuth API
BREAKING: OAuth Redirect Flow redirect with errors
Action required UpdateIn 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 PKCEaccess_denied
: The user cancelled the redirect flow intentionallyinvalid_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
Changes to Variant paper_weight_unit value
Action required UpdateWe 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 asgrammage
will be converted to the equivalent metric unitgsm
-gsm
will be the only accepted value when creating or updating Variants from this date If you are creating or updating Variants now, please setpaper_weight_unit
togsm
and be prepared to handle this value in any API response which includes Variant information.
- Zaikio Hub API
BREAKING: /connections and /subscriptions
Action required UpdateThe API endpoints
GET /connections
ANDGET /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 relationsfirst
,prev
,next
andlast
can be present.Current-Page
The current page of the paginated response (starting at 1)Total-Count
The total number of items in this collectionTotal-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 onGET /subscriptions
:filters[subscriber_id]
e.g.Organization-d2e78ba7-5cfc-4359-9d8a-43ce0fa3a795
and onGET /connections
:filters[connectable_id]
e.g.Organization-d2e78ba7-5cfc-4359-9d8a-43ce0fa3a795
Further Reading: Zaikio Hub API Reference to be released
- Procurement API
Links for nested SKUs on OrderLineItems will return null if the SKU has been deleted
UpdateAll endpoints that retrieve OrderLineItems with nested SKU data, will now return
null
for thelinks
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
DEPRECATED: /blacklisted_access_tokens
Action required UpdateThe API endpoints
GET/POST /blacklisted_access_tokens
is deprecated and got renamed toGET/POST /revoked_access_tokens
. The attribute also got renamed torevoked_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
DEPRECATED: site_id in machines
Action required UpdateThe 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 PATCHmachines/{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 ReferencePOST /machines/{machine_id}/ownership
- Zaikio Hub API
OAuth Credentials: Name and description
New UpdateFrom 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 wasmy_app
it can now also bemy_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
In Redirect Flow and Device Flow an organization can be pre-selected
New UpdateIt 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
API returns if email of person was confirmed
New UpdateWe 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
Person Bearer: Restrictions on sites and machines
Action required UpdateIf 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
First name can be null
Action required UpdateSince 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 benull
. We recommend to always use thefull_name
to display a name. - Zaikio Hub API
New: Create Organizations
NewIt 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 ReferencePOST /person/organizations
- Zaikio Hub API
New: Revoke OAuth Access Tokens
NewYou 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 ReferencePOST /blacklisted_access_tokens
- Hub Events
New: Loom events for member lifecycle events
NewWe 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
New: sites write OAuth Scope and endpoint
New UpdateYou 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
ordirectory.sites.rw
.
Further Reading: Zaikio Hub API Reference - Zaikio Hub API
New: sites read OAuth Scope
New UpdateThe 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, thesite_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
Users can not connect to foreign and unreviewed Apps in production
Action required UpdateIt 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
Person: new attribute unit_system and locale en-US
New UpdateThe person endpoint now returns a new attribute named
unit_system
. This can be eithermetric
orimperial
. 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
Country code and currency for all organization and person responses
NewFrom now on, all responses from organisations and persons will contain a
country_code
and acurrency
attribute, the currency attribute being derived from the country code. The attributes can benull
if the country was not provided by the organisation or person.
Further Reading: Zaikio Hub API Reference - Hub Events
New Connection Lifecycle Loom Events
NewWith 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
JWT Issuer (iss) changes from CP to ZAI
Action required UpdateJSON web tokens created by the Zaikio Hub are now issued by
ZAI
, before it wasCP
. Since you most likely do not work with this attribute, nothing needs to be done. - Loom API
Loom API migrated to loom.zaikio.com
Action required UpdateThe Loom event changed its domain to
loom.zaikio.com
(respectivelyloom.sandbox.zaikio.com
for the sandbox environment). - Zaikio Hub API
New connections endpoint and connected attribute
NewIt 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 theconnected
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
Event Webhook URL is now managed in the App configuration
Action required UpdateIn 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
Client Credentials Flow: The bearer must first grant access to the app
Action required UpdateRequested 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
OAuth Scopes in directory are limited to certain bearer types
Action required UpdateAs 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 forPerson
directory.organization.r
,directory.organization_members.r
=> only forOrganization
This does not change the functionality, as these scopes will not work with another Bearer type. - Zaikio Hub API
Accept only desired scopes
Action required UpdateRequested scopes must be created as
Desired Scopes
in the directory app, otherwise a new scope errorscope_is_not_included_in_desired_scopes
(see scope errors) is returned. - Zaikio Hub API
Delegations only usable for confidential clients
Action required UpdateThe 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
Events require valid subject
Action required UpdateFrom 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
On behalf of Person for Client Credentials Flow released
NewThe 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
Private apps take effect
Action required UpdateFrom 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 toExternal
in the app's details pane. - Zaikio Hub API
Scope Restriction
Action required UpdateScopes 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
Roles endpoint
NewYou 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
Organization endpoint
NewYou 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.