Developer Changelog

RSS Feed, Atom Feed, JSON Feed

• 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

  ---

• 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 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.

  ---

• 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 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.

  ---

Filter by: