API Conventions

Invoking APIs

The Factern APIs are exposed using JSON over HTTP, using the POST method.

Ex.

POST https://api.factern.com/v2/createentity
{
    "parentId": "00000000156F212E6B4BB8E079D483CA073254692F7725B2"
}

One can use a tool like curl for invoking the Factern API. Ex.

curl -XPOST 'https://api.factern.com/v2/createentity' -H 'Content-Type: application/json' -d'
{
    "parentId": "00000000156F212E6B4BB8E079D483CA073254692F7725B2"
}
'

Throughout this document, in the interests of brevity, we often use a short-hand that omits the domain, version and parameters.

Ex.

POST /createentity
{
    "parentId": "00000000156F212E6B4BB8E079D483CA073254692F7725B2"
}

API Authentication

Factern is compatible with a number of authentication schemes, including shared secret, PKI and OAuth 2.0.

Out-of-the-box, Factern supplies a builtin OAuth 2.0 server:

https://sso.factern.com

If you are using the builtin OAuth 2.0 server, you must use that server to acquire an authentication token, that you must supply on every Factern API call. This token can be acquired for example:

curl -XPOST 'https://sso.factern.com/auth/token' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -H 'Accept: application/json' \
    -H 'Authorization: Basic M0QxRDkwQ0RFNEI0QjQ3QzE1NTQzNEFCOUU2Q0FCQzkwNTkzQzVEOTUzREQwMTVFOm5weDg1OVNJdjhDbzFiWi9zOGV0U0czYkhWN2xLSGZ2ZmNuWkdGaEVOWFhPTFl6b0VVMVkvR3VDNi94UExIemdBOXl4RUxNWitETXd0VUtFS292OVJtTEtWYk5qUFVjcHdkM1paVTY5dHpTZ0hZRFhUeUg5VHlqelpSYmsvTk8xZkk1SGx0ZndIeFpYTFNpWDlkZFg5d2tsWXBqc0ZlZTlYd3JucUkvR1Ftdz0=' \
    -d'grant_type=client_credentials'

The magic Authorization value is just an example, here, and is calculated from your application Factern Id and application secret (here using python):

import base64
app_id = '00000000E4B4B47C155434AB9E6CABC90593C5D953DD015E'
app_secret = 'npx859SIv8Co1bZ/s8etSG3bHV7lKHfvfcnZGFhENXXOLYzoEU1Y/GuC6/xPLHzgA9yxELMZ+DMwtUKEKov9RmLKVbNjPUcpwd3ZZU69tzSgHYDXTyH9TyjzZRbk/NO1fI5HltfwHxZXLSiX9ddX9wklYpjsFee9XwrnqI/GQmw='
base64.urlsafe_b64encode("%s:%s" %(app_id, app_secret))

The app_id and app_secret values are those you received in response when you created the application.

The response from the POST to sso.factern.com will be of form:

{
    "access_token": "eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJhdWQiOiI4ZmY2ZjMxZi1hNjZiLTRlMGMtOGYyZC04N2MwMzc2ZTE1Y2IiLCJpc3MiOiJodHRwczpcL1wvc3NvLmZhY3Rlcm4uY29tXC9hdXRoXC8iLCJleHAiOjE0OTU1NDk5MDEsImlhdCI6MTQ5NTU0NjMwMSwianRpIjoiNDZjNGZkNDAtNjJlOS00M2NiLTlmZTgtYTI2ZTViN2RkYTNhIn0.F402AMctzVq7Kui2vthfDTCLfS4ImBqhbe8iRk7AJtLNkkj-52pwq2ySBSM3_QqizU-rz6UnJFat7qGXRro0eiYxk98ljcIEQ8iHFvgrosXpGJTrxG-OBLzYIissbEQjpysKQ7P_5UD7Cq-ZW5p8v29Ezs2kmZYV1sauSYZIAxN8cdphsIF2km6mjPm2MRVcvWbx49NGvkJ-HkAz_Bxc172cAzsLnD0gRZwVZgttzhZrTgEf21Nzho_EDuFUicpS02fTQvO53Hf9XPRnZtYHg4Q7k9XM8SIvj76x2FclxWhQZ-VyqXHIstMe2S6g-KugTDVTDGSuhALKBxwjaXY-Rw",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "address phone email openid profile"
}

It is the access_token value you will need to supply on each call to api.factern.com. An example use of this then (to create an entity):

curl -XPOST 'https://api.factern.com/v2/createentity?user=000000002763084B71BF685830B74B23C8316EBCA1B55785&operatingAs=000000002763084B71BF685830B74B23C8316EBCA1B55785' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJhdWQiOiI4ZmY2ZjMxZi1hNjZiLTRlMGMtOGYyZC04N2MwMzc2ZTE1Y2IiLCJpc3MiOiJodHRwczpcL1wvc3NvLmZhY3Rlcm4uY29tXC9hdXRoXC8iLCJleHAiOjE0OTU1NDk5MDEsImlhdCI6MTQ5NTU0NjMwMSwianRpIjoiNDZjNGZkNDAtNjJlOS00M2NiLTlmZTgtYTI2ZTViN2RkYTNhIn0.F402AMctzVq7Kui2vthfDTCLfS4ImBqhbe8iRk7AJtLNkkj-52pwq2ySBSM3_QqizU-rz6UnJFat7qGXRro0eiYxk98ljcIEQ8iHFvgrosXpGJTrxG-OBLzYIissbEQjpysKQ7P_5UD7Cq-ZW5p8v29Ezs2kmZYV1sauSYZIAxN8cdphsIF2km6mjPm2MRVcvWbx49NGvkJ-HkAz_Bxc172cAzsLnD0gRZwVZgttzhZrTgEf21Nzho_EDuFUicpS02fTQvO53Hf9XPRnZtYHg4Q7k9XM8SIvj76x2FclxWhQZ-VyqXHIstMe2S6g-KugTDVTDGSuhALKBxwjaXY-Rw \
    -d '
{
    "parentId": "00000000156F212E6B4BB8E079D483CA073254692F7725B2"
}'

The user and operatingAs parameters are the login and representing login Factern Ids, with just example values here. The JSON payload is also just an example. The Authorization: Bearer AUTH_TOKEN token is the value of the previously returned access_token.