OAuth authentication / “Connect with eventyay”

In addition to static tokens, eventyay supports OAuth2-based authentication starting with eventyay 1.16. This allows you to put a “Connect with eventyay” button into your website or tool that allows the user to easily set up a connection between the two systems.

If you haven’t worked with OAuth before, have a look at the OAuth2 Simplified tutorial.

Registering an application

To use OAuth, you need to register your application with the eventyay instance you want to connect to. In order to do this, log in to your eventyay account and go to your user settings. Click on “Authorized applications” first and then on “Manage your own apps”. From there, you can “Create a new application”.

You should fill in a descriptive name of your application that allows users to recognize who you are. You also need to give a list of fully-qualified URLs that users will be redirected to after a successful authorization. After you pressed “Save”, you will be presented with a client ID and a client secret. Please note them down and treat the client secret like a password; it should not become available to your users.

Obtaining an authorization grant

To authorize a new user, link or redirect them to the authorize endpoint, passing your client ID as a query parameter. Additionally, you can pass a scope (currently either read, write, read write or profile) and an URL the user should be redirected to after successful or failed authorization. You also need to pass the response_type parameter with a value of code. Example:

https://eventyay.com/api/v1/oauth/authorize?client_id=lsLi0hNL0vk53mEdYjNJxHUn1PcO1R6wVg81dLNT&response_type=code&scope=read+write&redirect_uri=https://eventyay.com

To prevent CSRF attacks, you can also optionally pass a state parameter with a random string. Later, when redirecting back to your application, we will pass the same state parameter back to you, so you can compare if they match.

After the user granted or denied access, they will be redirected back either to the redirect_url you passed in the query or to the first redirect URL configured in your application settings.

On successful registration, we will append the query parameter code to the URL containing an authorization code. For example, we might redirect the user to this URL:

https://eventyay.com/?code=eYBBf8gmeD4E01HLoj0XflqO4Lg3Cw&state=e3KCh9mfx07qxU4bRpXk

You will need this code parameter to perform the next step.

On a failed registration, a query string like ?error=access_denied will be appended to the redirection URL.

Note

By default, the user is asked to give permission on every call to this URL. If you only request the profile scope, i.e. no access to organizer data, you can pass the approval_prompt=auto parameter to skip user interaction on subsequent calls.

Getting an access token

Using the code value you obtained above and your client ID, you can now request an access token that actually gives access to the API. The token endpoint expects you to authenticate using HTTP Basic authentication using your client ID as a username and your client secret as a password. You are also required to again supply the same redirect_uri parameter that you used for the authorization.

POST /api/v1/oauth/token

Request a new access token

Example request:

POST /api/v1/oauth/token HTTP/1.1
Host: eventyay.com
Accept: application/json, text/javascript
Authorization: Basic bHNMaTBoTkwwdms1M21FZFlqTkp4SFVuMVBjTzFSNndWZzgxZExOVDplSmpzZVA0UjJMN0hMcjBiS0p1b3BmbnJtT2cyY3NDeTdYaFVVZ0FoalhUU0NhZHhRTjk3cVNvMkpPaXlWTFpQOEozaTVQd1FVdFIwNUNycG5ac2Z0bXJjdmNTbkZ1SkFmb2ZsUTdZUDRpSjZNTWFYTHIwQ0FpNlhIRFJjV1Awcg==

grant_type=authorization_code&code=eYBBf8gmeD4E01HLoj0XflqO4Lg3Cw&redirect_uri=https://eventyay.com

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "access_token": "i3ytqTSRWsKp16fqjekHXa4tdM4qNC",
  "expires_in": 86400,
  "token_type": "Bearer",
  "scope": "read write",
  "refresh_token": "XBK0r8z4A4TTeR9LyMUyU2AM5rqpXp"
}
Status Codes:

As you can see, you receive two types of tokens: One “access token”, and one “refresh token”. The access token is valid for a day and can be used to actually access the API. The refresh token does not have an expiration date and can be used to obtain a new access_token after a day, so you should make sure to store the access token safely if you need long-term access.

Using the API with an access token

You can supply a valid access token as a Bearer-type token in the Authorization header to get API access.

GET /api/v1/organizers/ HTTP/1.1
Host: eventyay.com
Authorization: Bearer i3ytqTSRWsKp16fqjekHXa4tdM4qNC

Refreshing an access token

You can obtain a new access token using your refresh token any time. This can be done using the same token endpoint used to obtain the first access token above, but with a different set of parameters:

POST /api/v1/oauth/token HTTP/1.1
Host: eventyay.com
Accept: application/json, text/javascript
Authorization: Basic bHNMaTBoTkwwdms1M21FZFlqTkp4SFVuMVBjTzFSNndWZzgxZExOVDplSmpzZVA0UjJMN0hMcjBiS0p1b3BmbnJtT2cyY3NDeTdYaFVVZ0FoalhUU0NhZHhRTjk3cVNvMkpPaXlWTFpQOEozaTVQd1FVdFIwNUNycG5ac2Z0bXJjdmNTbkZ1SkFmb2ZsUTdZUDRpSjZNTWFYTHIwQ0FpNlhIRFJjV1Awcg==

grant_type=refresh_token&refresh_token=XBK0r8z4A4TTeR9LyMUyU2AM5rqpXp

The previous access token will instantly become invalid.

Revoking a token

If you don’t need a token any more or if you believe it may have been compromised, you can use the revoke_token endpoint to revoke it.

GET /api/v1/oauth/revoke_token

Revoke an access or refresh token. If you revoke an access token, you can still create a new one using the refresh token. If you revoke a refresh token, the connected access token will also be revoked.

Example request:

POST /api/v1/oauth/revoke_token HTTP/1.1
Host: eventyay.com
Accept: application/json, text/javascript
Authorization: Basic bHNMaTBoTkwwdms1M21FZFlqTkp4SFVuMVBjTzFSNndWZzgxZExOVDplSmpzZVA0UjJMN0hMcjBiS0p1b3BmbnJtT2cyY3NDeTdYaFVVZ0FoalhUU0NhZHhRTjk3cVNvMkpPaXlWTFpQOEozaTVQd1FVdFIwNUNycG5ac2Z0bXJjdmNTbkZ1SkFmb2ZsUTdZUDRpSjZNTWFYTHIwQ0FpNlhIRFJjV1Awcg==

token=XBK0r8z4A4TTeR9LyMUyU2AM5rqpXp

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
Status Codes:

If you want to revoke your client secret, you can generate a new one in the list of your managed applications in the eventyay user interface.

Fetching the user profile

If you need the user’s meta data, you can fetch it here:

GET /api/v1/me

Returns the profile of the authenticated user

Example request:

GET /api/v1/me HTTP/1.1
Host: eventyay.com
Accept: application/json, text/javascript
Authorization: Bearer i3ytqTSRWsKp16fqjekHXa4tdM4qNC

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "email": "admin@localhost",
  "fullname": "John Doe",
  "locale": "de",
  "is_staff": false,
  "timezone": "Europe/Berlin"
}
Status Codes: