KanBo API 2.7
Last modified:
Configuring KanBo app
If you want to use KanBo API via KanBo.Client.dll you have to first configure your KanBo app. Inside web.config file in section <kanbo><authentication> you have to register X509 certificate that will be used for authentication (you can even generate it by yourself using makecert, see CreateCert.ps1 in Api Sample) .
Download KanBo API samples here:
Use the sample for 2.7 version.
As shown above, there are different provider types for certificates:
- “AppSingedLogin” – when using this provider type your service will be seen as user which login you provide and will have exactly same permissions as that user.
On-prem login will look like this: `i:0#.w|domain\user` `domain\user` O365 login will look like this `i:0#.f|membership|[email protected]` `[email protected]`
XML:
<provider id="login" type="AppSignedLogin">{signer}</provider>
- “AppSignedUser” – when using this provider type your service will be seen as user defined by you in code and will have exactly same permissions as that user.
XML:
<provider id="user" type="AppSignedUser">{signer}</provider>
- “AppSignedService” – when using this provider type your service will be seen as Service and will have permissions defined by KanBo - full access to everything on KanBo.
XML:
<provider id="app" type="AppSignedService" name="Test service">`{signer}</provider>
The `signer` declares which certificate will be used to validate the signature of given token, possible types are:
- **X509SignerFromFile** - contains a public or private key read from a file by specified path (you can use either .cer or .pfx here, pfx file will need a key).
XML:
`<signer type="X509SignerFromFile" file="c:\.ssl\kanbo_id.pfx" key="MyKanBo" />` `<signer type="X509SignerFromFile" file="c:\.ssl\kanbo_id.cer" />`
- **X509SignerFromStore** - contains a public or private key read from a certificate in given certificate store by specified property.
XML:
`<signer type="X509SignerFromStore" storeName="My" storeLocation="CurrentUser" key="Thumbprint" value="A89369E6705C2B3E446AF5DD5A2A1B559F913152" />` `<signer type="X509SignerFromStore" storeName="My" storeLocation="LocalMachine" key="Thumbprint" value="a89369e6705c2b3e446af5dd5a2a1b559f913152" />` `<signer type="X509SignerFromStore" storeName="My" storeLocation="LocalMachine" key="Thumbprint" value="a8 93 69 e6 70 5c 2b 3e 44 6a f5 dd 5a 2a 1b 55 9f 91 31 52" />` `<signer type="X509SignerFromStore" storeName="My" storeLocation="LocalMachine" key="SerialNumber" value="a89369e6705c2b3e446af5dd5a2a1b559f913152" />` `<signer type="X509SignerFromStore" storeName="My" storeLocation="LocalMachine" key="SubjectName" value="MyFancyApp" />`
Example:
Parameters required for KanBo API object creation:
- kanboUrl – base url of KanBo web (example: "https://kanboapp.developer.local")
- instanceId – id of an KanBo instance (only for KanBo versions lower than 2.7)
- userId – id of a user our service will impersonate (only for userToken). Example: 1
- loginName= login of kanbo user - required for login type security token. Example: "i:0#.w|developer\\administrator"
- certificatePath – path for the certificate that was registered in KanBo web.config
- certificatePassword – password to certificate mentioned above
- duration- it will define for how long the token is valid (after that it's re-issued)
- it's suggested to use the default value, however if your clocks are synchronized, if not, you may consider using [special tokens that synchronize your client with server](https://bitbucket.org/objectconnect/kanbo-additionaltokens)
- UserToken – if we want our app to work as signed user (AppSignedUser provider)
- ServiceToken – if we want our app to work as signed service (AppSignedService provider)
- LoginToken – if we want our app to work as signed user (AppSignedLogin provider)
- MobileToken
Creating API object
To create our KanBo API object first we need to create security token. There are several types of tokens:
Here are examples on how to create all token types:
- Generating token for user scope
var loginToken = new LoginToken(KanBoIssuers.Login, loginName, TimeSpan.FromMinutes(10), userCer);
- Generating token for user scope
var userToken = new UserToken(KanBoIssuers.User, userId, TimeSpan.FromMinutes(10), userCer);
- Generating token for service scope
var serviceToken = new ServiceToken(KanBoIssuers.Service, TimeSpan.FromMinutes(10), userCer);
- Generating mobile token
var mobileToken = new MobileTokenSource("administrator", "adminpassword", "https://kanboapp.developer.local");
Next there is need to create requester object for our api.
Example:
var jsonRequester = new JsonApiRequester(mobileToken, kanboUrl, httpClient);
Last step is to create API object with use of a chosen requester:
- Creating API object
var api = new Api(jsonRequester);
- creating uploader object for file upload
var uploader = new Uploader(kanboUrl, jsonRequester);
Calling methods
All methods in our API can be called in the following manner:
- Get Groups in a Board
var groups = await api.GetData(KanBoGetDataMethods.GroupsInBoard, new { BoardId = 2 });
- Get information about this kanbo api method argumets
var info = await api.GetMethodInfo(KanBoGetDataMethods.Board);
- Get current user
var usr = await api.GetData(KanBoGetDataMethods.CurrentUser, new { });
- Getting board
var board = await api.GetData(KanBoGetDataMethods.Board, new { Id = 2 });
- Uploading file to Board and attaching it to card
await Upload(145, uploader, api);
Available methods
There are 2 types of KanBo API methods:
- GetData methods
- Actions methods
You can download a document containing a whole list of KanBo API methods by clicking here.