komoot - OAuth2 documentation
https://auth-api.main.komoot.net/
Connect a 3rd party app with komoot via OAuth2
Komoot offers 3rd party apps access to planned and tracked tours on behalf of a user. From your app, initiate an OAuth2 connect
with komoot to get access to a user's profile and tours.
You need OAuth2 credentials, a client-id
and a client-secret
to perform the following steps. Ask your account manager at komoot to retrieve them.
As part of the standard OAuth2 connect process, you will retrieve two kinds of keys: A long-lived refresh_token
and a short-lived access_token
. You can only use the access_token
to retrieve data from the komoot API and you need the refresh_token
to (re)create an access_token
on expiration.
The base URL for OAuth2 is https://auth-api.main.komoot.net/oauth, thus the /authorize
endpoint can be found at https://auth-api.main.komoot.net/oauth/authorize and the token can be retrieved via https://auth-api.main.komoot.net/oauth/token.
To get started, we recommend you check out our example OAuth2 client and test the authentication and API access flow. The demo client connects to the komoot API and retrieves your komoot tour list. You'll see extensive HTTP logging, showing all request headers and bodies.
Examples (using cURL)
The following sections will lead you through the authorization and authentication of API requests. All of the following examples use cURL for a simplified demonstration of HTTP calls. The documentation of the OAuth endpoints can be found at the bottom of the page.
Authorization Flow
We offer different OAuth2 grant types.
The first and default is the authorization_code
grant type.
Devices with limited input capabilities (e.g. watches) or devices which don't have a browser, or only an old browser, should use the device_code
grant type. Instead of redirecting the user to the website where they can log in, in the device_code
grant type you show a code and a URL on the screen. The user then needs to open the URL on another device which has a browser and type in the code there. The watch/device polls the API while showing the user code. The API returns OAuth2 tokens once the user completed the approval flow in the web browser.
Authorization with the "authorization code" grant type
## Authorize
# Initiates the authentication flow
curl 'https://auth-api.main.komoot.net/oauth/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=YOUR_REDIRECT_URL&scope=profile%20tour-upload'
This request will return a 302 HTTP status code, with the Location
header pointing to the komoot login page, which you need to follow. Regardless of whether the user authorized your application or not, the redirect URL is called.
When the user authorization was not successful, the call to the redirect URL contains error=access_denied
as query parameter.
In case of a successful login it includes the code
parameter in the query.
This code
is used to retrieve the access token.
## Access Token
# Retrieve a token for the user
curl -X POST https://auth-api.main.komoot.net/oauth/token \
--user 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' \
-d 'redirect_uri=YOUR_REDIRECT_URL' \
-d 'grant_type=authorization_code' \
-d 'code=CODE' \
-H 'Accept: application/json' \
This returns a JSON containing the access_token
which is then used to authorize requests to the komoot API (Bearer Authentication).
In addition to the access_token
, it also contains various other properties like the komoot username. See an example response below:
{
"access_token": "the_access_token",
"token_type": "bearer",
"refresh_token": "the_refresh_token",
"expires_in": 59,
"scope": "the space separated list of scopes",
"username": "username_of_the_user",
"jti": "a338c2f9-4bb0-4912-8a3e-faff4309e28b"
}
Authorization with the "device code" grant type
# Fetch the code and URL the user has to go to
curl -X POST https://auth-api.main.komoot.net/v1/clients/YOUR_CLIENT_ID/device_code/ \
--user 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' \
-d 'scope=profile tour-upload'
{
"user_code": "ABCD-EFGH",
"device_code": "YourDeviceCodeForPollingTheApi",
"expires_in": 119, # remaining seconds. Both codes will be invalid after that time.
"verification_url": "https://komoot.com/devices", # start url to show on the watch
"interval": 2 # max polling interval in seconds. You need to wait for the number of seconds before sending the next request. Otherwise you'll be rate-limited.
}
The device needs to show the verification_url
and the user_code
to the user and instruct them to go to that URL in their logged-in browser and type in the code. Until the user types in the code on the verification URL page and approves the process, poll the API every interval
seconds.
curl -X POST https://auth-api.main.komoot.net/oauth/token \
--user 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' \
-d 'grant_type=device_code' \
-d 'device_code=YOUR_DEVICE_CODE_FOR_POLLING_THE_API'
This either returns a 204 HTTP status code which tells that the device/watch should poll again (respect the polling interval). Or it returns a 400 with an error access_denied
if the user canceled the flow.
If the user successfully completed the flow then a 200 HTTP status code is returned. The response JSON contains the access_token
which is then used to authorize requests to the komoot API (Bearer Authentication).
In addition to the access_token
, it also contains various other properties like the komoot username. See an example response below:
{
"access_token": "the_access_token",
"token_type": "bearer",
"refresh_token": "the_refresh_token",
"expires_in": 59,
"scope": "the space separated list of scopes",
"username": "username_of_the_user",
"jti": "a338c2f9-4bb0-4912-8a3e-faff4309e28b"
}
Perform Authenticated API Request
The access_token
is now valid for expires_in
seconds. During the time that it is valid, it can be used to perform requests against the API. In order to authorize an API request you need to add the Authorization: Bearer YOUR_ACCESS_TOKEN
header to each request.
## Perform authenticated API Request
# Uses the access token to retrieve the tours of the user (username of current user can be taken from the token response)
curl https://external-api.komoot.de/v007/users/USERNAME/tours/ \
-H 'Authorization: Bearer USER_ACCESS_TOKEN'
Refresh Authentication Token
The access token
expires after a certain time (see expires_in
in the response of /token
endpoint). Clients should remember this time and refresh expired tokens before sending the next API request. If you make a request with an expired access_token
, the API will return a HTTP status code 401 and return a JSON that mentions that the token is expired, e.g.:
{
"error": "invalid_token",
"error_description": "Access token expired: here_is_the_access_token_of_the_request"
}
There is no need to perform the full authorization flow another time, instead a new token can be retrieved by using the refresh_token
. The access token endpoint (which is requested as the last request of the authorization flow) returns a refresh_token
in addition to the access_token
. This token can be used to request a new access_token
once the access_token
has expired. In order to retrieve a new access_token
using the refresh_token
, the "/token" endpoint is used, like you can see in the following example:
## Access Token
# Refresh the access token for the user
curl -X POST https://auth-api.main.komoot.net/oauth/token \
--user 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' \
-d 'refresh_token=REFRESH_TOKEN' \
-d 'grant_type=refresh_token' \
-H 'Accept: application/json' \
-u 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET'
If the refresh token request returns a 400 HTTP status code with { "error": "invalid_grant" }
in the JSON body, it means that the connection was terminated by the komoot user. Then you need to perform the full authorization flow again, by showing the login screen or the device code.
Authorize a 3rd party client to access komoot on behalf of a user
Initiates the Auth flow which redirects to the komoot login and afterwards back to the redirect URI. In more detail, this request will return a 302 to the komoot login page which you need to follow. Regardless of whether the user did successfully login and authorize your application or if he canceled, the redirect URL is called. When the user authorization was not successful, the call to the redirect URL contains error=access_denied
as query parameter. In case of a successful login it includes the code
parameter in the query.
Authorize a 3rd party client to access komoot on behalf of a user using the device_code grant type
Initiates the Auth flow returns a code and a verification URL. This information must be displayed to the user so that he/she can go to the verification URL and type in the code there. In the next step, the user finishes the usual OAuth2 approval flow. The device/watch polls the API while showing the user code. The API returns OAuth2 tokens once the user completed the approval flow in web.
Obtain access token and refresh token for a user
Retrieve an access token for the user. The redirect_uri
supplied to the authorize call will be called on success as well as on failure. On success the query includes the code
necessary to retrieve the token and the state
that was passed into the authorize request. In case of an error the query on the redirect URL will contain no code, instead it contains error=access_denied
. A 400 with grant_type=refresh_token and { "error": "invalid_grant" }
in the JSON body means the refresh token is no longer valid / the user disconnected. In this case you need to perform the full authentication again (aka show the login screen or start the device code flow).
Disconnect connection of user
Allows to "log out" a user by removing the refresh token and with that disconnect a user's connection.
Allows to "log out" a user by removing the refresh token and with that disconnect a user's connection.