Authentication

The ObexCode Sync Server API uses the OAuth protocol to authenticate requests for access to protected resources. However, because no third parties are involved in any API transaction, only the final resource-access stage is required. Pre-authorized Access Tokens are created in the portal.

1. Generate Consumer and Access Token

Each portal user is identified by a consumer key, and each application or website should be identified by its own Access Token. Both of these are created via the OAuth Tokens section of the portal.

Create a new Access Token by entering a label for it into the first row of the table on the aforementioned page, and either press enter or select Create. If you do not yet have a consumer key at this point, one will automatically be generated for you in the Access Token creation process.

Both consumer key and Access Tokens will not automatically expire, and can be used repeatedly. Should you believe any to be compromised, your consumer key can be regenerated, and Access Tokens can be removed/revoked.

2. Access protected resource

Every attempt to access protected resources needs to include several oauth parameters in the request. If you are already familiar with, or wish to use an existing oauth library, the values generated in the previous step should be enough to start interfacing with the API.

For those unable or unwilling to use an existing library, authentication can be performed by supplying the necessary oauth parameters in either the HTTP Authorization header (recommended) or in the query parameters:

Request with header

Authorization: OAuth realm="",
    oauth_version="1.0",
    oauth_nonce="[single-use value]",
    oauth_timestamp="[seconds since UNIX epoch]",
    oauth_signature_method="PLAINTEXT",
    oauth_consumer_key="[consumer key]",
    oauth_token="[access key]",
    oauth_signature="[consumer secret]%26[token secret]"

Request with query string

GET http://api.obexcode.com/v2/phones/vendors/all.xml?oauth_version=1.0
&oauth_nonce=single-use-value&oauth_timestamp=seconds-since-UNIX-epoch
&oauth_signature_method=PLAINTEXT&oauth_consumer_key=consumer-key
&oauth_token=access-key&oauth_signature=consumer-secret%26token-secret

oauth_nonce

This should be a randomly-generated, single-use value, unique among requests for the given timestamp.

oauth_timestamp

This should be the standard POSIX timestamp of when the request was created; the number of seconds since the UNIX epoch (1970-01-01 00:00:00 UTC).

oauth_consumer_key

This is the 'key' value, not the secret, associated with your consumer key.

oauth_token

This is the 'key' value associated with the Access Token you want to use.

oauth_signature

When using the oauth_signature_method "PLAINTEXT", this is a concatenation of your consumer secret, a URL-encoded ampersand ('%26') and your token secret.

For convenience, each Access Token information page supplies an HTTP Authorization header template, pre-filled with the required keys. If viewed over a secure connection (https), the signature value will also have the consumer and token secrets filled out.

Notes on security

When using the oauth_signature_method of "PLAINTEXT" in a production environment, it is imperative that API requests are only performed over a secure channel (ie. https), to protect them from being trivially compromised.

The oauth_signature_method of "HMAC-SHA1" is also supported, and can safely be used over non-https connections, but is considerably more involved in its implementation. Refer to the OAuth documentation for detailed information should you wish to implement HMAC-SHA1 signing yourself.