Skip to main content
All CollectionsAssembla BasicsLearn More
Getting Started with Assembla Developer API
Getting Started with Assembla Developer API
Toshi Dávila avatar
Written by Toshi Dávila
Updated over 2 weeks ago

Understanding terminology

The terminology we use is from Oauth2 in addition to Assembla terminology.

  • A Client is your application registered on the Assembla site. Use the ID and secret to identify the application for which you want to generate access tokens.

  • Access Tokens are used to generate user sessions. Tokens have a 15-minute timeout which resets when the token is used. If an access token is expired, you can use a refresh token to generate a new one without authentication.

  • Refresh Tokens are used to generate new access tokens without asking authentication from users. Refresh tokens have a 31-day timeout which resets when the token is used.

  • Bearer Tokens are security tokens. Any party in possession of the token (a "bearer") can use the token in any way that any other party in possession of it can.

Registering your application

To start using the API, first register a client. A client is your application registered on the Assembla site. Send the ID and secret with basic authentication in your authorization requests to identify the application for which you want to generate access tokens.

Complete the following fields in order to register your app:

  • Name. A user-defined name that identifies the application (required).

  • Website URL. The URL to the application web site.

  • Redirect URL. The callback URL on your application. Users are redirected here with an access token or an authorization code. Usable for web services only. If you plan to use Web service flow authentication, be sure to complete this field, otherwise you receive an error.

Caution! Sharing your client ID and secret can give someone else the ability to generate access tokens for your application and authenticate requests you may not want, keep them safe.

Understanding the Assembla Developer API

Assembla Developer API provides resources used by external applications, using a secure authentication mechanism (OAuth 2) and based on REST architecture.

Starting with your application

After you create a client, you are able to generate access tokens and authenticate user sessions. To generate an access token, see authentication documentation page.

Using resources and URL schema

The API is accessible at https://api.assembla.com

API resources reside in the /api URL namespace. You can fetch a typical API resource from: https://api.assembla.com/_version/path/to/resource

Using HTTP verbs

The following is a list of HTTP verbs for the Assembla API with a response status:

  • GET Retrieve an array of resources or an identified resource.

  • POST Create a resource.

  • PUT Update an identified resource. PUT requests do not return any body in responses, to get the body of the updated object request with GET to the same URL.

  • DELETE Delete an identified resource.

Understanding authentication

Assembla uses Oauth2 to authenticate users from external applications. Available authentication flows include:

  • Web service suitable for browser-based applications.

  • Client credentials suitable for applications that rely on public data and do not require user authentication.

  • Pin Code suitable for desktop/mobile applications.

  • Refresh tokens not strictly an authorization flow, but by using refresh tokens, you can generate new access tokens without authenticating again with available refresh tokens.

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

Using requests

A request to an API resource should include:

Required items

  1. Authorization. Bearer _your_token HTTP header.

  2. .xml or .json termination of URLs to identify data type you want to request from the server.
    ​Note: Consider requesting JSON instead of XML, because JSON is much faster.

  3. Client ID and secret sent via basic authentication.

Conditional items

  1. Content-type. application/(xml,json) header, data can be presented to server in three formats:

    • query string (no Content-type)

    • application/xml

    • application/json

  2. Send body data type sent based on Content-type HTTP header i.e. Content-type header is set to application/xml you have to send an XML body, application/json for JSON. If no Content-type is set, data should be a query string.

Here is an example request, using cURL utility:

$ curl -H "Authorization: Bearer 9c04c84ea5e85d5aaa788ac74af60d3f" -u "dtE8rqjW8r4yJWadbNA33N:4bfc7bbab6cc34aa38f2297a1d12465f" https://api.assembla.com/v1/spaces/test-1/tickets.json

  • Bearer access token: 9c04c84ea5e85d5aaa788ac74af60d3f

  • Client ID: dtE8rqjW8r4yJWadbNA33N

  • Client secret: 4bfc7bbab6cc34aa38f2297a1d12465f

Note: You can use only HTTPS on API requests; HTTP requests are redirected to HTTPS.

Note: Assembla accepts only UTF-8 and UTF-8 compliant data. Please make sure your data is encoded correctly.

Understanding responses

Items you must pay attention to in API responses:

  • HTTP Status header, result of the operation. Check the Statuses and Errors section for more info.

  • Content-type, body data type requested in API request.

  • Location HTTP header, POST operations only, the URL of newly created resource.

  • Response body, not present on PUT operations, data body formatted as requested.

Here is an example XML response:

HTTP/1.1 200 OK
Server: nginx/0.8.55
Date: Tue, 11 Jun 2024 12:14:24 GMT
Content-Type: application/xml; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Status: 200
...

<?xml version="1.0" encoding="UTF-8"?>
...

Example JSON response:

HTTP/1.1 200 OK
Server: nginx/0.8.55
Date: Tue, 11 Jun 2024 12:16:06 GMT
Content-Type: application/json; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Status: 200
...

[...]

Note: Some response bodies are paginated, in this case page and per_page parameters are available where maximum value for per_page is 100, bigger values are ignored and set to 10. Follow request documentation to find out if pagination is available.

Understanding statuses and errors

Statuses on successes:

  • 200 OK Success from a GET, PUT, or DELETE operation.

  • 201 Created Success from a POST operation.

  • 204 No Content Success from a GET operation with empty data.

Statuses on errors:

  • 422 Unprocessable Entity Data you sent to the server cannot be processed, or a validation error occurred.

  • 404 Not Found Resource cannot be found.

  • 403 Forbidden Request Cannot authorize.

  • 500 Internal Server Error Server is experiencing an unknown error.

Troubleshooting some of these errors:

  • 422 Unprocessable Entity Assert request Content-type with data type sent. For example, if you try to send a JSON body with Content-type: application/xml, the server interprets your JSON body as XML and cannot process it.

  • 404 Not Found Check resource identifier. Also check whether the resource you requested was not deleted or not yet created.

  • 500 Internal Server Error Check the integrity of the data you send (verify closing tags of XML body and validity, verify JSON validity). If the error persists, please contact us.

Using rate limitations

Assembla Developer API allows you to execute not more than 240 requests per minute with burst of 20 requests per second. When you exceed the rate limit, requests are terminated with error code 429 (Too Many Requests).


For more information, check out our API Documentation Site.

If you have any questions or need our assistance, don't hesitate to contact us at support@assembla.com. 

Did this answer your question?