Here's a short introduction to the Tehden API. The API follows the OAuth 2.0 specification. Text encoding is always UTF-8. Keep in mind that at the moment the API can change without notice. Remember to always use API version 1. You can access Tehden API documentation here: apidoc.tehden.com
Adding a new client
If you need a new client you can request it from api.support@tehden.com
Getting an access token
- The "password" method uses API client specific user credentials. This is the recommended method.
- The "authorization code" method has two steps and requires that an end-user approves the request.
Authorization code: Asking for authorization
The client redirects the user to
GET https://somecompany.tehden.com/oauth/oauser/authorize
Parameters in URL (because it's a redirect).
Parameters
- client_id: client to be authorized
- response_type: defines authorization type, currently Tehden only supports "code" (Authorization code).
- (optional) redirect_uri: must be in the same domain as what is stored in the database during registering
- (optional) scope: space delimited list of requested scopes
- (optional) state: a string that is always returned the same to the client, for state handling on client side
Result
- If allowed, the user is redirected to the URL in the database (or parameters) with response parameters
- redirect_uri?state=WHAT_WAS_GIVEN&code=AUTHORIZATION_CODE
Authorization code: Getting access token with authorization code
Client must authenticate either by
- Authorization header "Authorization: Basic HASH_DIGEST" where HASH_DIGEST is base64 encoded string of "client_id:client_secret"
- Adding client_id and client_secret as GET/POST parameters
GET/POST https://somecompany.tehden.com/oauth/oaclient/token
Parameters
- grant_type: Tehden supports "authorization_code" which is used to verify user's approval
- code: the authorization code
- redirect_uri: must be identical with the redirect_uri given in the "Authorization code: Asking for authorization" part
- + client credentials (client_id and client_secret) if authenticating using GET/POST parameters
Result
JSON object with the following fields:
- access_token: access token used to access the API
- expires_in: time in seconds after which the access token expires
- token_type: "Bearer" supported by Tehden
- scope: list of scopes allowed, string delimited by spaces
- refresh_token: a token that can be used to get a new access token after it expires
After the response the authorization code is unusable.
Password: Requesting an access token
Client must authenticate either by
- Authorization header "Authorization: Basic HASH_DIGEST" where HASH_DIGEST is base64 encoded string of "client_id:client_secret"
- Adding client_id and client_secret as GET/POST parameters
GET/POST https://somecompany.tehden.com/oauth/oaclient/token
Parameters
- grant_type: Tehden supports "password" which is used for API client specific users
- username: the username of the API client user
- password: the password of the API client user
- redirect_uri: must be identical with the redirect_uri given in the "Authorization code: Asking for authorization" part
- + client credentials (client_id and client_secret) if authenticating using GET/POST parameters
Result
- JSON object with the following fields
- access_token: access token used to access the API
- expires_in: time in seconds after which the access token expires
- token_type: "Bearer" supported by Tehden
- scope: list of scopes allowed, string delimited by spaces
- refresh_token: a token that can be used to get a new access token after it expires
Refreshing access token
Client must authenticate the same way as is described in "Getting access token with authorization code".
GET https://somecompany.tehden.com/oauth/oaclient/token
Parameters in URL
Parameters
- grant_type: string "refresh_token"
- refresh_token: the refresh token aquired earlier
- (optional) scope: if asking for an additional scope
- + client credentials (client_id and client_secret) if authenticating using GET/POST parameters
Result
-
The same JSON as in the previous "Getting access token with authorization code" section
Making API calls
GET/POST ;https://somecompany.tehden.com/api/module/methodwhere "module" can be e.g. company, customer, general and "method" is the function name.
Authorization header "Authorization: Bearer HASH_DIGEST" where HASH_DIGEST is base64 encoded string of the access token.
API version must be defined either as a GET parameter (e.g. "version=1") or as an Accept header (e.g. "Accept: application/vnd.tehden.api-v1+json").
Language code must be set either as a GET parameter (e.g. "language=fi") or as an Accept-Language header (e.g. "Accept-Language: fi"). Valid values at the moment are "fi" and "en".
The response is in JSON.
Errors
Possible error codes
- Bad request 400 = bad syntax or something missing
- Unauthorized 401 = problem with authorization
- Forbidden 403 = token does not have required scope
- Not found 404 = valid syntax, but does not exist
- Internal error 500 = server side problems
- Not implemented 501 = resource not implemented
Testing
It is possible to test the API using the following settings on a test server. Replace "somecompany" with the subdomain of your company.
- server: https://somecompany.elcustomer.net/
- client_id: MyApiClient
- client_secret: MySecret
- redirect_uri: http://localhost
Example
The following example tries to do everything the easiest way possible. We will only use the GET method here to keep things simple. Normally you should always use the POST method.
After the application has been registered to Tehden, you will have a client id (e.g. "MyApiClient") and a client secret (e.g. "MySecret"). The application also has to have a redirect URI (e.g. "https://www.example.com/apicallback") where the client browser will be redirected after the user allows the application to access Tehden.
Let's start by authorizing the application "MyApiClient" to use Tehden as the current user in company "Some Company". You need to be logged in as a Tehden user in order for this to work.
GET https://somecompany.tehden.com/oauth/oauser/authorize?client_id=MyApiClient&response_type=code
Once you allow access you are redirected to the redirect uri which was defined during the client application registration. In this example the redirect looks like thisGET https://somecompany.tehden.com/oauth/oaclient/token?grant_type=authorization_code&code=1v3ba0f2797fcfebdefc9ac5ba8dd839fbab579110cc14abf0eaabe0bc7d&client_id=MyApiClient&client_secret=MySecret
We get the following response in JSON.
{"access_token":"1v3da014885cad15ca57b506112a51771b1ac870b9dbc85947a02e483966",
"expires_in":3600,
"token_type":"bearer",
"scope":"",
"refresh_token":"1vb3c273bad35e9cfc6dcc97f02631cca7bbcd2f25fcb19b321a2c855d84"}
From now on we can make API calls using the access_token. In this example it will expire after an hour. The API will also respond by giving an "invalid_grant" error if you try to use an expired access token. You can get a new access token using the refresh_token.
GET https://somecompany.tehden.com/oauth/oaclient/token?grant_type=refresh_token&refresh_token=1vb3c273bad35e9cfc6dcc97f02631cca7bbcd2f25fcb19b321a2c855d84&client_id=MyApiClient&client_secret=MySecret
{"access_token":"1v98951702e28f9e4795c31c949131da627049221000315df8079ecefecc",
"expires_in":3600,
"token_type":"bearer",
"scope":"",
"refresh_token":"1vf41d4aaf2dddf85c5fe5fdc27f599da48374fa96b5d9eb729ca2183e11"}
An example API call to get all product groups:
GET https://somecompany.tehden.com/api/product/getProductGroups?version=1
Remember to add the Authorization header. In this case it will be (using the latest access token encoded in base64, everything written on one line):
Authorization: Bearer MXY5ODk1MTcwMmUyOGY5ZTQ3OTVjMzFjOTQ5MTMxZGE2MjcwNDkyMjEwMDAzMTVkZjgwNzllY2VmZWNj
Same request in curl
curl \
-H "Accept: application/vnd.tehden.api-v1+json" \
-H "Accept-Language: fi" \
-H "Authorization: BearerMXY5ODk1MTcwMmUyOGY5ZTQ3OTVjMzFjOTQ5MTMxZGE2MjcwNDkyMjEwMDAzMTVkZjgwNzllY2VmZWNj" \
https://somecompany.tehden.com/api/product/getProductGroups
<?php
header('Content-Type: text/plain');
// Fill in the access token
$accessToken = '<valid_access_token_here>';
// Change the product_ids
$post = array(
'product_ids' => array(
'8319e522-8a6e-4cdf-a605-075e0c4a8d18',
'db86f94b-de3b-49ab-8bf3-8e3b14bc6b67'
)
);
$headers = array(
'Accept: application/vnd.tehden.api-v1+json',
'Accept-Language: fi',
'Authorization: Bearer ' . base64_encode($accessToken)
);
$ch = curl_init('https://somecompany.tehden.com/api/product/getProducts');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($post));
$response = curl_exec($ch);
curl_close($ch);
$response = json_decode($response);
var_dump($response);
Kommentit
0 kommenttia
Kirjaudu sisään jättääksesi kommentin.