Authorization
goUrban uses Json Web Tokens (JWT) passed as Bearer tokens inside the Authorization HTTP Header to authenticate and authorize requests against resources.
Authentication
- Retrieve JWT access and refresh tokens through signing in with API credentials (API id and key).
- That returns access and refresh token. The access token has a short lifetime. Refreshing the access token (generating a new one) can be done by using the refresh token, which has a long lifetime. Both lifetimes are configurable.
- Refresh the JWT access token by using the refresh token.
Error Codes
Find a list of error codes in the document below:
Disclaimer: The API response will not include fields that have been set to null. It is the responsibility of the developer using the API to handle any missing fields on their end. This decision is subject to change and any updates will be reflected in the API documentation.
Terms & Conditions Handling
When accessing resources for which acceptance of Terms & Conditions is a requirement, the user needs to have accepted the latest version of the T&C associated with that resources. This basically applies to all resources except the ones which are also available without authentication.
The current T&C for a branch can be requested with https://user-api.docs.gourban.co/terms & conditions/terms and conditions by branch id
Additionally, the T&C can also be requested for a specific vehicle with https://user-api.docs.gourban.co/terms & conditions/terms and conditions by vehicle id
When accessing resources without accepting (latest) T&C for that resource an error is returned. See the Terms and Conditions section in Error Codes for a complete list of the error codes related to T&C. The following are the most important:
- U601 you haven't agreed to the terms and conditions yet.
- U602 you haven't agreed to the latest terms and conditions yet.
User Handling
When accessing the goUrban MaaS API your application is using an API User to access resources for:
- Creating users, which are managed by the application and are meant to be impersonated
- Modifying managed users
- Accessing resources on behalf of managed/impersonated users
The application needs to keep track of the users it manages by using the ID (UUID) of the managed users. The UUID is returned after the creation of a user is done.
Additionally, the application can use the customProperties field of the user to store additional data like its own user id to make cross-referencing easier.
User types
The goUrban backend differentiates between 3 types of users:
- Verified Users: These are meant for users which access the goUrban backend by identifying themselves with email/password or phone/code. A typical use case is an end-user app that directly accesses the goUrban backend.
- API Clients: These are meant for external applications, which are accessing resources of the goUrban backend. A typical use case is an external application that manages users on its own but uses resources of the goUrban backend.
- Impersonate Users: These are users managed by an external application and mapped to verified users managed by that external application. This user can only be used by API Clients in combination with impersonation.
Internationalization
In order to enable an international operation of shared vehicle fleets a branch where a user, promotion, or alike will operate has to be passed in some of the actions made in the goUrban landscape.
The most important use cases for sending branches are the following:
- User creation - Defines the home branch (home-billable-branch) of the user
- Voucher redemption - The passed billable branch defines on which balance the money will reside.
- Package buy - The passed billable branch defines in which wallet the money will reside.
Terminology:
- Home Branch (home-billable-branch): This branch defines where the home base of the user is. Meaning, that in case the user wants to rent a vehicle outside of his home billable branch he/she will be roaming.
- Roaming: In the goUrban sense this means that a user can't buy packages and is limited to pay-as-you-go payment methods.
How to:
In order to identify the applicable branch to be used for the above-mentioned operations, we provide a branch resolver API endpoint that takes a user location as an input and returns a list of billable branches. This list is ordered by distance (closest first) and can then be used for sending the appropriate branch.
API: /branch/resolver
Docs-Reference: https://user-api.docs.gourban.co/branches/resolve
ATTENTION: In case no user location is sent the branch resolver will return the fallback branch defined by the operator.
