Authenticating with the API¶

The API provides an oAuth2 compatible authentication and authorization method. Both the Authorization Code and Device Code grant types are supported.

Create an app¶

Send an URL-encoded POST request to /apps to create an app. The parameters are the following:

Example:

POST https://mobilizon.fr/apps
content-type: application/x-www-form-urlencoded

name=Mobilizon+Event+Importer&redirect_uris=https%3A%2F%2Fmyapp.com%2Fcallback%0Ahttps%3A%2F%2Fmyapp.com%2Fcallback2&website=https%3A%2F%2Fjoinmobilizon.org&scope=write%3Aevent%3Acreate+write%3Aevent%3Aupdate+write%3Aevent%3Adelete

It returns a JSON-encoded payload with your submitted data plus client_id, which identifies your app, and client_secret, which will be used in some cases later. Please note the values of client_id and client_secret somewhere as they will both be used later.

Example successful response.

{
  "client_id": "D4X8v1zmNrVMjukcPy4ceN/T1phWOyhXtHNuyMsQBw",
  "client_secret": "b6lBDMUN+Q8hecHKNRVxCHDGasLELGWbZ+vgFqV7s3",
  "name": "Mobilizon Event Importer",
  "redirect_uri": ["https://myapp.com/callback", "https://myapp.com/callback2"],
  "scope": "write:event:create write:event:update write:event:delete",
  "website": "https://joinmobilizon.org"
}

Authorization Code grant type¶

Authorizing the app¶

Send the user to GET /oauth/authorize to authorize your app. The following query parameters are required:

After the user approves your app, it will be redirected to the value of redirect_uri with the following query parameters:

Exchanging the authorization code for tokens¶

Submit a POST request to /oauth/token with the following parameters:

Mobilizon will return a JSON-encoded payload with in particular values for access_token and refresh_token.

Response parameters:

The access token can now be used through the Authorization header like the following: Authorization: Bearer [access_token].

Example successful response:

{
  "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJtb2JpbGl6b24iLCJleHAiOjE2Nzc4ODk5NDEsImlhdCI6MTY3Nzg2MTE0MSwiaXNzIjoibW9iaWxpem9uIiwianRpIjoiYTVkMDU4NGUtMTY2My00OTc3LTk1N2UtYjZjZjk1ZTlmYzgxIiwibmJmIjoxNjc3ODYxMTQwLCJzdWIiOiJBcHBUb2tlbjoxMiIsInR5cCI6ImFjY2VzcyJ9.7D6FPNRmSSZ8HDYh0GT12G_cPSF-UH_XfpQU1dGiOa9ADULciiQIKYnsrYP0QVrKnSWLfdP06d0SiCksQTSjKQ",
  "expires_in": 28800,
  "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJtb2JpbGl6b24iLCJleHAiOjE2OTM1ODU5NDEsImlhdCI6MTY3Nzg2MTE0MSwiaXNzIjoibW9iaWxpem9uIiwianRpIjoiMTQ1MDk3NGMtOWE4NS00YmI3LWE5NTktODg5OGM5NzQxM2UzIiwibmJmIjoxNjc3ODYxMTQwLCJzdWIiOiJBcHBUb2tlbjoxMiIsInR5cCI6InJlZnJlc2gifQ.Ttn1PlqV3RZkewdwM-EIEgJwN8XTWB_PtmYSTkVCb7U7TrLqF5pVnN1brubj_ePLFohweLaJWah6X5ajNFNdrg",
  "refresh_token_expires_in": 15724800,
  "scopes": "write:event:create write:event:update write:event:delete",
  "token_type": "bearer"
}

Device Code grant type¶

Authorizing the app¶

Step 1: App requests the device and user verification codes from Mobilizon¶

Submit a POST request to /login/device/code with the following parameters:

The response will be a JSON-encoded payload with the following values:

Example successful response:

{
  "device_code": "FWMWGMPNCCNUPCWBKNNNPBGYUJZGRUDGRVMOQJQM",
  "expires_in": 900,
  "interval": 5,
  "user_code": "MZQO-TGIC",
  "verification_uri": "https://mobilizon.fr/login/device"
}

Step 2: Prompt the user to enter the user code in a browser¶

Your device will show the user verification code and prompt the user to enter the code at https://my-mobilizon-instance.tld/login/device.

Step 3: App polls Mobilizon to check if the user authorized the device¶

Your app will make device authorization requests that poll POST /oauth/token, until the device and user codes expire or the user has successfully authorized the app with a valid user code. The app must use the minimum polling interval retrieved in step 1 to avoid rate limit errors.

The user must enter a valid code within 15 minutes (or 900 seconds). After 15 minutes, you will need to request a new device authorization code with POST /login/device/code.

Once the user has authorized, the app will receive an access token that can be used to make requests to the API on behalf of a user.

The endpoint takes the following input parameters.

Mobilizon will return a JSON-encoded payload with in particular values for access_token and refresh_token.

Response parameters:

The access token can now be used through the Authorization header like the following: Authorization: Bearer [access_token].

Example successful response:

{
  "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJtb2JpbGl6b24iLCJleHAiOjE2Nzc4ODk5NDEsImlhdCI6MTY3Nzg2MTE0MSwiaXNzIjoibW9iaWxpem9uIiwianRpIjoiYTVkMDU4NGUtMTY2My00OTc3LTk1N2UtYjZjZjk1ZTlmYzgxIiwibmJmIjoxNjc3ODYxMTQwLCJzdWIiOiJBcHBUb2tlbjoxMiIsInR5cCI6ImFjY2VzcyJ9.7D6FPNRmSSZ8HDYh0GT12G_cPSF-UH_XfpQU1dGiOa9ADULciiQIKYnsrYP0QVrKnSWLfdP06d0SiCksQTSjKQ",
  "expires_in": 28800,
  "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJtb2JpbGl6b24iLCJleHAiOjE2OTM1ODU5NDEsImlhdCI6MTY3Nzg2MTE0MSwiaXNzIjoibW9iaWxpem9uIiwianRpIjoiMTQ1MDk3NGMtOWE4NS00YmI3LWE5NTktODg5OGM5NzQxM2UzIiwibmJmIjoxNjc3ODYxMTQwLCJzdWIiOiJBcHBUb2tlbjoxMiIsInR5cCI6InJlZnJlc2gifQ.Ttn1PlqV3RZkewdwM-EIEgJwN8XTWB_PtmYSTkVCb7U7TrLqF5pVnN1brubj_ePLFohweLaJWah6X5ajNFNdrg",
  "refresh_token_expires_in": 15724800,
  "scopes": "write:event:create write:event:update write:event:delete",
  "token_type": "bearer"
}

Authentication¶

Access token¶

To access protected operations and contents, the access token must be added in the Authorization header of the HTTP request as the bearer.

Here is an example with curl command :

curl -sS \
  -H 'accept: application/json' \
  -H "Authorization: Bearer eyJXXXJ9.eyJxxxQ.SXXX5c" \
  -F "query=${gql}" \
  -F "variables=${vars}" \
  "${MOBILIZON_ENDPOINT}"

In graphiql playground, there is a button to add headers :

Other HTTP clients may have other ways to setup the bearer.

Refresh token¶

When access token is expired, protected operations will return a 401 code.

In that case, the access token must be renewed using the refresh token using the refreshToken mutation.

mutation RefreshToken($rt: String!) {
  refreshToken(refreshToken: $rt) {
    accessToken
    refreshToken
  }
}

You get back an access token and a refresh token which replace the previous ones.