Over 618,748 projects created

Summary


Assembla uses Oauth2 to authenticate users from external applications, available authentication flows are:

  1. Key/Secret credentials suitable for development environment, small one-user applications.
  2. Web service suitable for browser based applications.
  3. Client credentials suitable for applications that rely on public data and do not require user authentication.
  4. Pin Code suitable for desktop/mobile applications.
    • Refresh token not strictly an authorization flow, using refresh tokens you can generate new access tokens without authenticating again with available refresh tokens.

Any authentication flow will return a bearer access token. To authenticate your requests to API resources add the Authorization: Bearer \_token HTTP header to your request headers list.

Client applications


A client is an application registered on Assembla. Every API request will require client id and secret provided with basic auth.

  • Client ID, client identifier.
  • Client secret, used with identifier to specify the client you want to generate access tokens for.
  • Redirect URL or callback URL, used only for web services authorization flow, this is the authorization endpoint where a client generates access tokens and user sessions.

Note: The common authentication URL you will see will have this format:

https://_client_id:_client_secret@api.assembla.com/...

This is how basic authorization credentials are injected into the URL, different applications will implement basic authentication in different formats, please be aware.

Authorization flows


Api key/secret authentication flow


Accessing an API resource is possible without an access token via API key and secret (find your API key and secret on applications management page). Using this flow you can authentication your own Assembla user without requesting an access token.

Suitable for development, in case you don’t care about authentication or write a bot programm.

To get the authentication send headers below with your credentials:

X-Api-Key: _key
X-Api-Secret: _secret

A cURL example would be:

curl -H "X-Api-Key: 8a71541e5fb2e4741120" -H "X-Api-Secret: a260dc4448c81c907fc7c85ad09d31306c425417" https://api.assembla.com/path/to/resource/...

Asuming:

  • 8a71541e5fb2e4741120 is the key
  • a260dc4448c81c907fc7c85ad09d31306c425417 is secret

Note: If you appending an Authorization: Bearer _token header next to key/pair credentials the priority will be on access token and key/secret authentication will be ignored.


Web services or 3-step authentication flow


Web services flow is a 3-step based authorization mechanism that requires a browser redirect to Assembla API authorization page. Suitable for browser based applications only.


Step 1: redirect user to Assembla API authorization page:


Request an authorization code, do so by redirecting your user to the following URL.

https://api.assembla.com/authorization?client_id=_client_id&response_type=code


Step 2: callback URL


When user accepts authorization it will be redirected to redirect URL you have specified when registered client application.

URL query string will include ?code=_authorization_code parameter, exchange it for an access token in step 3.

Timeout of an authorization code is 60 seconds, so exchange it immediately.


Step 3: exchange authorization code for an access token


Send a POST request to

https://_client_id:_client_secret@api.assembla.com/token?grant_type=authorization_code&code=_authorization_code

Where _authorization_code is the code you have received in query string.

If data is provided correctly you will be returned a JSON body containing an access token and data attached to it:

{
  "token_type":"bearer",
  "access_token":"5332ef83e48f6389b64fe3e1f24cdc39",
  "expires_in":899,
  "refresh_token":"y3g2eh83e48fv389b64fe3e1fk4blp58"
}

Client credentials


Suitable for applications that rely on public data and do not require user authorization.

To create a client token send a POST request to:

https://_client_id:_client_secret@api.assembla.com/token?grant_type=client_credentials

An expected output should be a JSON body:

{
  "token_type":"bearer",
  "access_token":"c3161681e7a69f0a2ed060a59f331d7d",
  "expires_in":899
}

Note: No refresh token is attached to client access tokens, so a client session has a 15 minutes timeout

Pin code


The PIN code authorization flow is designed for applications that cannot use a browser to get redirected to authorization endpoint, instead a PIN code is displayed after successful user authentication. Authorization process is similar to web service flow process, but a PIN code will be displayed instead of a redirect to callback URL.

To generate a PIN code, run a web browser on URL:

https://api.assembla.com/authorization?client_id=_client_id&response_type=pin_code

A PIN code will be generated and displayed as on the screenshot:

image

Request this PIN code inside your application and send a POST request to:

https://_client_id:_client_secret@api.assembla.com/token?grant_type=pin_code&pin_code=_pin_code

In case of success a JSON body with access token is returned:

{
  "token_type":"bearer",
  "access_token":"94c70d470e391bdc16a8d8363b5d4891",
  "expires_in":899,
  "refresh_token":"a341718c1c8573f2702a5884ed5e04c5"
}

Note: PIN codes have 24 hours expiration timeout.

Refresh tokens


Refresh tokens are used to generate new access tokens without asking users for authorization. Access tokens apart from tokens generated with client credentials flow have a refresh token attached. Refresh tokens have 31 days timeout.

Send a POST request to

https://_client_id:_client_secret@api.assembla.com/token?grant_type=refresh_token&refresh_token=_refresh_token

In case of success a JSON body is returned with a new access token

{
  "token_type":"bearer",
  "access_token":"c031511ad5fcec5c3f614d3fd9d35dc3",
  "expires_in":899
}

After this operation refresh token remains the same and it’s expiration time is reset to 31 days.

Authorized requests


An API request should always include the Authorization: Bearer _access_token header or X-Api-key: _api_key and X-Api-secret: _api_secret pair in request HTTP headers list.

Example of valid API requests using cURL utility:

$ curl -H "Authorization: Bearer 94c70d470e391bdc16a8d8363b5d4891" https://api.assembla.com/v1/path/to/resource.json

or with api key/secret pair:

$ curl -H "X-Api-key: 84ca218c0bd44ce28a84" -H "X-Api-secret: 9aa1ae7dbffcf1168e2d7a88130dc0ce57bf2211" https://api.assembla.com/v1/path/to/resource.json

Do not provide both authorization token and api key/secret pair, in this case token will be used.

References