Documentation - CDE Services

1. Overview

The CDE Services website allows internal and external developers to access services and APIs that the California Department of Education (CDE) makes available. After registering an account on this website, developers can request a "Service Token" which grants them the ability to make data requests to the respective CDE Service. By clicking on the Dashboard link after logging in to your account, you can see which CDE Services you have access to (if you do not see an expected CDE Service, please contact us to request access). You can get more information for each service by clicking on its title on the Dashboard.

2. Obtain a Service Token

Once you have confirmed you have access to a CDE Service (if you see a CDE Service on your Dashboard, then you have some level of access to it), there are 2 ways to generate a Service Token with which to make requests:

Use the Generate Token button (useful for non-expiring or one-time-use Service Tokens)

On the Dashboard page, click the button for the respective CDE Service. This will generate a Service Token and then display it in the CDE Service box. You must use this Service Token in any HTTP data requests to the CDE Service.

Send a POST request (useful for Service Tokens that expire and require refreshing)

From your application, send a POST request to this endpoint:

https://services.cde.ca.gov/token/request

Make sure to include 3 parameters in the request:
'accountname': The account name that you registered with,
'password': The password that you registered with,
'serviceid': The ID of the service for which you're requesting the token (you can find it on the Dashboard page)

A sample request would look similar to:

POST https://services.cde.ca.gov/token/request HTTP/1.1
Host: services.cde.ca.gov
Content-Type: application/json;charset=utf-8

{"accountname":"[YOUR ACCOUNT NAME]","password":"[YOUR ACCOUNT PASSWORD]","serviceid":"[SERVICE ID]"}

You will receive a response similar to this:

HTTP/1.1 200 OK
Content-Length: 669
Content-Type: application/json;charset=UTF-8
Server: Microsoft-IIS/8.0
{
"service_token": "123456789012345678901234567890123456789012345678901234567890",
".created": "2016-09-02 10:35 AM PDT"
".expires": "2016-09-03 10:35 AM PDT"
}

3. Request data with a Service Token

When you are ready to get data from a CDE Service, you must include your Service Token in the header of each HTTP request. For example, consider a theoretical CDE Service called the XYZ Service which returns phone numbers.

Some sample jquery code may look like:

$.ajax({
    dataType: "json",
    url: https://services.cde.ca.gov/xyz/api/phone/1,
    headers: { "service_token": "123456789012345678901234567890123456789012345678901234567890" },
    success: function (data) {
        alert(JSON.stringify(data, undefined, 2));
    }

The request header would look similar to:

GET https://services.cde.ca.gov/xyz/api/phone/1 HTTP/1.1
Host: services.cde.ca.gov
Accept: */*
service_token: 123456789012345678901234567890123456789012345678901234567890
X-Requested-With:XMLHttpRequest

You would receive a response similar to:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Server: Microsoft-IIS/8.0
Content-Length: 27
{
"phone_number": "916-555-1234"
}

You can learn more about the individual CDE Services by clicking a service name from the Dashboard page. The link should take you to the CDE Service's landing page with more information.

4. Revoke a Service Token

Under some circumstances you may feel you need to revoke a Service Token (usually due to security concerns). Again there are 2 ways to accomplish this.

Use the Revoke Token button

On the Dashboard page, click the button. You will confirm the revocation, which can take up to 60 seconds to propagate fully.
Send a POST request

In your application, send a POST request to this endpoint:
```
https://services.cde.ca.gov/token/revoke
```
Make sure to include the 'token' parameter in the request.

A sample request would look similar to:
```
POST https://services.cde.ca.gov/token/revoke HTTP/1.1
Host: services.cde.ca.gov
Content-Type: application/json;charset=utf-8

{"service_token":"123456789012345678901234567890123456789012345678901234567890"}
```
The response will be a 200 OK if the request was formulated correctly. You can verify that the Service Token has been revoked by viewing your Dashboard page.