DAP API and API key vs. client ID + secret: please clarify if any changes apply to the low level API

[pgo586]

I don't have experience yet using the DAP CLI (or client library). I've only used so far the low level DAP API (REST), and I've recently been confused by some of the posts that suggest that API Keys have been deprecated (or will eventually be) for use with the API. In particular, when I look at the official API documentation, I still see that it refers to API keys (and not client ids + secrets). Here's the Identity Services link where I still see this: https://identity.instructure.com/login

Can somebody clarify this? 

[ColinMurtaugh]

The keys that we can manage via identity.instructure.com consist of a client ID and a secret. You use the client ID and secret to obtain a short-lived access token which is used to access the DAP API. See "How to call a service" in the DAP API docs.

The dap CLI / client library used to accept the access token directly (via environment variable or command-line parameter) but now it accepts the client ID and secret instead. The CLI/library will manage fetching (and refreshing) the access token for you, simplifying the process. 

I hope this helps -- let me know if it's not clear!

--Colin

[pgo586]

Hi Colin, the issue with that documentation, which I've seen, is that it tells you that you need to use your client ID and secret but it then points you to the link I was referring to above, in which you still generate an API key and not a pair. If what it means is that one should split the API key that one obtains into client ID and secret, then it is definitely NOT explained in the relevant docs, and it should be. BTW, not sure if you're aware, but during the CD2 Alpha period we had to use client ID, secret, and we moved to the API key during the Beta period. I wonder why the reversal now.... but that's another story. 

[ColinMurtaugh]

When I generate a new key at identity.instructure.com it gives me a client ID and a secret (separately). Do you get something different? 

[pgo586]

I see... the issue seems to be currently one of nomenclature in the docs. I hadn't really tried creating a new API key before I posted, because the page still reads '+ API key', so I didn't even think that it would generate a pair of client ID and secret (the keys I've generated in the past were one unique string). When I try creating a new key myself, I see that at the end of the process it is actually producing 2 values, as you suggest yourself. Thanks for following up on this @ColinMurtaugh . 

[LeventeHunyadi · Accepted solution]

I have reached out to the Identity Service team to clarify the documentation.

DAP alpha operated with Canvas ID and secret pairs. Canvas credentials are no longer accepted by DAP, in any form. DAP alpha used Canvas credentials because at that time, DAP only provided Canvas data.

DAP beta operated with client ID and secret issued by Instructure Identity Service, which were concatenated into a single string. This single string had been called API key, which was a misnomer.

DAP client library accepts a client ID and secret, which are concatenated internally when passing to the authentication service. Since the concatenation is an implementation detail, and client ID helps in identifying requests, we prefer specifying them separately.

I hope this helps give some context.

[pgo586]

Thanks @LeventeHunyadi . This definitely confirms the cause of my confusion. Nomenclature *definitely* needs to be updated in the Identity Service page to remove any mentions of an 'API key' which suggests that the DAP beta conventions are still in use. Thanks for reaching out to the team to clarify this docs (and hopefully the web page itself, as I explained)

[pgo586]

One more question @LeventeHunyadi , in order to update the auth workflow in my nodejs scripts (which use the low level API) to use client id and secret instead of API key , I've tried passing in the concatenated "<clientID>:<secret>" in the Axios REST call's Authorization header - in the same way the API key was being passed- , However, this does not work (I get a 403 response). Could you either suggest how to correct my code below, or share a nodejs (or any non-CURL) example that works? Here's my current code:

     const response = await axios({
          method: 'POST',
          url: authEndpoint,
          data: querystring.stringify(authData)
        , headers: {"Content-Type": "application/x-www-form-urlencoded", "Authorization": "Basic " +
        // 5/5/23 process.env.CD2ApiKey} // 12/7/22
        process.env.CD2ClientID + ":" + process.env.CD2Secret} // 5/5/23
    })

[pgo586]

Oh, I think I figured this one out myself (or actually, thanks ChatGPT for helping out! :-)) . Turns out that I needed to apply 'base64' to the individual key + secret values before concatenating them in the header. In the process, I've learned that one can have Axios itself do this conversion for you -and automatically create the Authorization header- by including an extra parameter in the configuration as follows: 
const response = await axios({
     method: 'POST',
     url: authEndpoint,
     auth: { username: process.env.CD2ClientID, password: process.env.CD2Secret}},
     data: querystring.stringify(authData),
     headers: {"Content-Type": "application/x-www-form-urlencoded"}
})

[LeventeHunyadi]

This is indeed the case, you have to apply base64 encoding to the concatenated string. This is what our Python code looks like in DAP client library:

base64.b64encode(f"{client_id}:{client_secret}".encode("utf-8")).decode("ascii")

Subsequently, you will need to pass the access token you receive in the response as the HTTP header X-InstAuth for future API requests.