We created our API from the ground up making sure we address the needs of developers
- Complete Documentation
- SDKs coming
Getting Started with the Saferize API
From an App developer perspective, there’s only a few concepts that we need to cover. In order to use Saferize, you need to make a few API calls on specific times during your application and listen and take action on some Webhook events. When a child signs up on your app or website, you make a call to our “/approvals” endpoint to check if that child can or cannot access the service. Saferize will then trigger the Parental Consent workflow. After we get a consent from a parent, we will issue a callback on your webhook endpoint “approving” that child. From that point on, every time that child logs in, you make a call to our “/sessions” endpoint. We will monitor and let you know via webhooks if the time is up or anything changed on that last approval.
- App: That’s your app or website. This object has all the attributes you need to identify, check and change the configuration of your app. You can change your Webhook URL on this object, for example.
- AppUser: An AppUser represents a child on a particular App. Every time a child signs up on your app and you make a call to Saferize, we create an AppUser to represent that child. You can use the “token” field to identify that AppUser on your system.
- Approval: Represents an Approval that you request for that AppUser to be able to use your App. An approval can have be APPROVED or REJECTED. Other features and time-restrictions can also be customized on the approval.
- Family: That object represent the Family of an user of your app. As an app developer, you cannot change attributes from the family, but you can see some information about them, such as who is the parent who approved the access and etc.
- Parent: Parents represent adults that belong to the family and can approve or change that AppUser. As an App developer.
- Child: A child is an AppUser across all apps that this child uses. From an app perspective it might just be another AppUser
How to Authenticate
When you first create your account with Saferize as an App you will be asked to generate an RSA private/public key pair. Please remember to store your private key on a safe place. Saferize will never ask for your private key. Every time you make a request, you need to generate a JWT token and sign using you private key. Our servers will use the public key we have on our system to validate that signature. Here are the fields we need for JWT:
Note that the maximum expiration time we accept on our tokens is 1 minute. We recommend having a shorter expiration time by default.
We version our API using the Accept header. A valid request must have an Accept header in the format
How to make an approval
An approval is created when a child first signs up. Here’s a sample approval request:
A few things to notice on this request:
- API Versioning happens on the Accept header so that header is required and it should be:
- The “token” field of the user object represents an user on your platform, this needs to be unique across all users of your service. A good suggestion for token is either an user Id or a nickname that your user has on your system.
Here’s a sample approval response:
As you can see, this approval is PENDING. That means that we still need to get in touch with that parent and get consent. Once we are able to get his consent we will send your webhook endpoint a POST request that looks like this:
You can see that this message tell us that approval for user with token “my token” has been “APPROVED”. The child can now access the service.
How to control sessions
Once the child has been approved, you can use the Saferize API to control their sessions. We are going to take care of time-limits, feature restrictions and etc. In order to do that, we need to make a couple of API calls: First we need to create a session for that user:
The server will return a session object that represents a session for that user.
You can see on the session response that this session has a duration of 3600 seconds based on what the parents decided, but you don’t have to worry about this as Saferize will send you a webhook notification when the session expires.
Do you want to know more?
Saferize offers a way to Publishers to increase revenue by charging parents for controlling and supervising how children interact with apps.