Skip to main content

Security and Errors

Security​

All API requests must be authenticated, which associates the request with a specific Member in the system. The results of the request will then be secured according to that Member's Roles defined within the system. A request that cannot be authenticated will result in a 401 Unauthorized response.

To authenticate, send a personal access token in the HTTP Authorization header using the Bearer scheme. Access tokens are created in the application from the Member's Applications settings, and each token can be revoked independently without changing the Member's credentials. The request is processed in the context of the Member the token belongs to.

Prefer access tokens

Basic Authentication with a username and password is not likely to be available: instances configured for single sign-on do not accept passwords for API requests, and administrators commonly disable password access entirely.

Errors​

When a request results in an error, the response will have an HTTP status code in the range 400-500, and detailed information about the error will be returned in the response payload.

For example, the request ~/rest-1.v1/Data/Story?sel=Bogus results in a 400 Bad Request response with this payload:

<Error href="/VersionOne/rest-1.v1/Data/Story?sel=Bogus">
	<Message>Invalid SEL parameter</Message>
	<Exception class="VersionOne.MetaException">
		<Message>Unknown AttributeDefinition: Story.Bogus</Message>
	</Exception>
</Error>

The response is an Error element, with an href attribute indicating the offending requested URL. The Message element contains a textual description of the error. Optional Exception elements may contain technical details about the cause of the error.

Common Error Status Codes​

400 Bad Request​

A 400 status code is the most common error, resulting from a request that could not be processed by the API. The Error Message will identify the specific problem, and there may be Exception elements that give very detailed information. The usual causes of this error are:

  • An invalid parameter on the query string.
  • An invalid payload on a POST request.

401 Unauthorized​

A 401 status code indicates that the request could not be authenticated. This may be caused by any one of these conditions:

  • No Authorization header or credentials supplied with the request.
  • An invalid or revoked access token.
  • An invalid username or password supplied to Basic Authentication, where it is enabled.

The typical course of action would be to obtain a valid access token and resend the request.

404 Not Found​

A 404 status code indicates that there is no resource to retrieve at the requested URL. This could be due to:

  • An invalid URL path requested.
  • A request for a single asset which does not exist, or is deleted, or is secured from the user's view.

405 Method Not Allowed​

A 405 status code indicates that the HTTP method used for the request is not valid at the requested URL. This will be returned for any method other than GET and POST, or if POST was sent to a URL that does not support updating.

500 Internal Server Error​

A 500 status code indicates that an unexpected error occurred during the processing of the request. The response payload will contain Exception elements with specific technical information that will help diagnose the cause of the error. This could be due to:

  • An environmental problem (e.g., the database is unavailable).
  • An unhandled exception within the Agility software.