## Authentication

Authentication — Authentication of web service requests

## Synopsis

    const char *        flickcurl_get_api_key               (flickcurl *fc);
    void                flickcurl_set_api_key               (flickcurl *fc,
                                                             const char *api_key);
    const char *        flickcurl_get_shared_secret         (flickcurl *fc);
    void                flickcurl_set_shared_secret         (flickcurl *fc,
                                                             const char *secret);
    const char *        flickcurl_get_auth_token            (flickcurl *fc);
    void                flickcurl_set_auth_token            (flickcurl *fc,
                                                             const char *auth_token);
    char *              flickcurl_auth_checkToken           (flickcurl *fc,
                                                             const char *token);
    char *              flickcurl_auth_getFrob              (flickcurl *fc);
    char *              flickcurl_auth_getFullToken         (flickcurl *fc,
                                                             const char *frob);
    char *              flickcurl_auth_getToken             (flickcurl *fc,
                                                             const char *frob);
    int                 flickcurl_auth_oauth_getAccessToken (flickcurl *fc);
    extern const char* const flickcurl_flickr_oauth_access_token_uri;
    extern const char* const flickcurl_flickr_oauth_authorize_uri;
    extern const char* const flickcurl_flickr_oauth_request_token_uri;
    const char *        flickcurl_get_oauth_client_key      (flickcurl *fc);
    void                flickcurl_set_oauth_client_key      (flickcurl *fc,
                                                             const char *client_key);
    const char *        flickcurl_get_oauth_client_secret   (flickcurl *fc);
    void                flickcurl_set_oauth_client_secret   (flickcurl *fc,
                                                             const char *client_secret);
    const char *        flickcurl_get_oauth_request_token   (flickcurl *fc);
    void                flickcurl_set_oauth_request_token   (flickcurl *fc,
                                                             const char *token);
    const char *        flickcurl_get_oauth_request_token_secret
                                                            (flickcurl *fc);
    void                flickcurl_set_oauth_request_token_secret
                                                            (flickcurl *fc,
                                                             const char *secret);
    const char *        flickcurl_get_oauth_token           (flickcurl *fc);
    void                flickcurl_set_oauth_token           (flickcurl *fc,
                                                             const char *token);
    const char *        flickcurl_get_oauth_token_secret    (flickcurl *fc);
    void                flickcurl_set_oauth_token_secret    (flickcurl *fc,
                                                             const char *secret);
    const char *        flickcurl_get_oauth_username        (flickcurl *fc);
    const char *        flickcurl_get_oauth_user_nsid       (flickcurl *fc);
    int                 flickcurl_oauth_create_request_token
                                                            (flickcurl *fc,
                                                             const char *callback);
    char *              flickcurl_oauth_get_authorize_uri   (flickcurl *fc);
    int                 flickcurl_oauth_create_access_token (flickcurl *fc,
                                                             const char *verifier);

## Description

Authentication of web service requests

## Details

### flickcurl_get_api_key ()

    const char *        flickcurl_get_api_key               (flickcurl *fc);

Get current application API Key (OAuth Client key)

`fc` : | flickcurl object
Returns : | API key or NULL if none set

### flickcurl_set_api_key ()

    void                flickcurl_set_api_key               (flickcurl *fc,
                                                             const char *api_key);

Set legacy Flickr auth application API Key (OAuth Client key)

For OAuth this is not sufficient and `flickcurl_set_oauth_client_key()` and `flickcurl_set_oauth_client_secret()` be used to pass both the client key and client secret.

`fc` : | flickcurl object
`api_key` : | API Key

### flickcurl_get_shared_secret ()

    const char *        flickcurl_get_shared_secret         (flickcurl *fc);

Get legacy Flickr auth Secret

`fc` : | flickcurl object
Returns : | shared secret or NULL if none set

### flickcurl_set_shared_secret ()

    void                flickcurl_set_shared_secret         (flickcurl *fc,
                                                             const char *secret);

Set legacy Flickr auth secret

`fc` : | flickcurl object
`secret` : | shared secret

### flickcurl_get_auth_token ()

    const char *        flickcurl_get_auth_token            (flickcurl *fc);

Get legacy Flickr auth Token

`fc` : | flickcurl object
Returns : | auth token or NULL if none set

### flickcurl_set_auth_token ()

    void                flickcurl_set_auth_token            (flickcurl *fc,
                                                             const char *auth_token);

Set legacy Flickr auth Token

`fc` : | flickcurl object
`auth_token` : | auth token

### flickcurl_auth_checkToken ()

    char *              flickcurl_auth_checkToken           (flickcurl *fc,
                                                             const char *token);

Get the credentials attached to an authentication token.

Implements flickr.auth.checkToken (0.9) Must be signed.

FIXME: Cannot confirm this works, get intermittent results.

`fc` : | flickcurl context
`token` : | token string
Returns : | permissions string or NULL on failure

### flickcurl_auth_getFrob ()

    char *              flickcurl_auth_getFrob              (flickcurl *fc);

Get a frob to be used during authentication

Implements flickr.auth.getFrob (0.9) Must be signed. Does not require authentication.

`fc` : | flickcurl context
Returns : | frob string or NULL on failure

### flickcurl_auth_getFullToken ()

    char *              flickcurl_auth_getFullToken         (flickcurl *fc,
                                                             const char *frob);

Turn a frob into an auth_token

Implements flickr.auth.getFullToken (0.5) Must be signed.

`fc` : | flickcurl context
`frob` : | frob string
Returns : | token string or NULL on failure

### flickcurl_auth_getToken ()

    char *              flickcurl_auth_getToken             (flickcurl *fc,
                                                             const char *frob);

Get the auth token for the given frob, if one has been attached.

Implements flickr.auth.getToken (0.9) Must be signed.

`fc` : | flickcurl context
`frob` : | frob string
Returns : | token string or NULL on failure

### flickcurl_auth_oauth_getAccessToken ()

    int                 flickcurl_auth_oauth_getAccessToken (flickcurl *fc);

Exchange tokens from the legacy Flickr auth to ones for OAuth

Calling this method will delete the legacy auth tokens used to make the request since they will expire within 24 hours of this call.

The OAuth token and secret should be saved and can be read from `flickcurl_get_oauth_token()` and `flickcurl_get_oauth_token_secret()`

Implements flickr.auth.oauth.getAccessToken (1.23)

`fc` : | flickcurl context
Returns : | non-0 on failure

### flickcurl_flickr_oauth_access_token_uri

    extern const char* const flickcurl_flickr_oauth_access_token_uri;

### flickcurl_flickr_oauth_authorize_uri

    extern const char* const flickcurl_flickr_oauth_authorize_uri;

### flickcurl_flickr_oauth_request_token_uri

    extern const char* const flickcurl_flickr_oauth_request_token_uri;

### flickcurl_get_oauth_client_key ()

    const char *        flickcurl_get_oauth_client_key      (flickcurl *fc);

Get OAuth Client Key (aka Consumer key, API Key)

See also `flickcurl_get_oauth_client_secret()`

`fc` : | flickcurl object
Returns : | client key or NULL if none set

### flickcurl_set_oauth_client_key ()

    void                flickcurl_set_oauth_client_key      (flickcurl *fc,
                                                             const char *client_key);

Set OAuth client key (aka API key)

See also `flickcurl_get_oauth_client_key()`

`fc` : | flickcurl object
`client_key` : | client key (API key)

### flickcurl_get_oauth_client_secret ()

    const char *        flickcurl_get_oauth_client_secret   (flickcurl *fc);

Get OAuth Client secret

See also `flickcurl_get_oauth_client_key()`

`fc` : | flickcurl object
Returns : | client secret or NULL if none set

### flickcurl_set_oauth_client_secret ()

    void                flickcurl_set_oauth_client_secret   (flickcurl *fc,
                                                             const char *client_secret);

Set OAuth client key (aka shared secret)

See also `flickcurl_set_oauth_client_secret()`

`fc` : | flickcurl object
`client_secret` : | client key (shared key)

### flickcurl_get_oauth_request_token ()

    const char *        flickcurl_get_oauth_request_token   (flickcurl *fc);

Get OAuth request token

`fc` : | flickcurl object
Returns : | request token or NULL if none set

### flickcurl_set_oauth_request_token ()

    void                flickcurl_set_oauth_request_token   (flickcurl *fc,
                                                             const char *token);

Set OAuth request token

See also `flickcurl_get_oauth_request_token()`

`fc` : | flickcurl object
`token` : | request token

### flickcurl_get_oauth_request_token_secret ()

    const char *        flickcurl_get_oauth_request_token_secret
                                                            (flickcurl *fc);

Get OAuth request token secret

`fc` : | flickcurl object
Returns : | request token secret or NULL if none set

### flickcurl_set_oauth_request_token_secret ()

    void                flickcurl_set_oauth_request_token_secret
                                                            (flickcurl *fc,
                                                             const char *secret);

Set OAuth request token secret credentials

See also `flickcurl_get_oauth_request_token_secret()`

`fc` : | flickcurl object
`secret` : | request token secret

### flickcurl_get_oauth_token ()

    const char *        flickcurl_get_oauth_token           (flickcurl *fc);

Get OAuth Token

`fc` : | flickcurl object
Returns : | auth token or NULL if none set

### flickcurl_set_oauth_token ()

    void                flickcurl_set_oauth_token           (flickcurl *fc,
                                                             const char *token);

Set OAuth Token

`fc` : | flickcurl object
`token` : | auth token

### flickcurl_get_oauth_token_secret ()

    const char *        flickcurl_get_oauth_token_secret    (flickcurl *fc);

Get OAuth token secret

`fc` : | flickcurl object
Returns : | secret or NULL if none set

### flickcurl_set_oauth_token_secret ()

    void                flickcurl_set_oauth_token_secret    (flickcurl *fc,
                                                             const char *secret);

Set OAuth token Secret

`fc` : | flickcurl object
`secret` : | shared secret

### flickcurl_get_oauth_username ()

    const char *        flickcurl_get_oauth_username        (flickcurl *fc);

Get the username for the authenticated user

`fc` : | flickcurl object
Returns : | username or NULL if none set

### flickcurl_get_oauth_user_nsid ()

    const char *        flickcurl_get_oauth_user_nsid       (flickcurl *fc);

Get the user_nsid for the authenticated user

`fc` : | flickcurl object
Returns : | user_nsid or NULL if none set

### flickcurl_oauth_create_request_token ()

    int                 flickcurl_oauth_create_request_token
                                                            (flickcurl *fc,
                                                             const char *callback);

Request an OAuth request token from Flickr for the application API Key/secret

Requires the OAuth Client key (API key) and Client secret to have been set with `flickcurl_set_oauth_client_key()` and `flickcurl_set_oauth_client_secret()` respectively.

Calls the Flickr OAuth endpoint to get a request token for the given callback or uses out-of-band if `callback` is NULL.

On success, stores the request token in the `fc` structure.

`fc` : | flickcurl object
`callback` : | callback URL or NULL for out of band
Returns : | non-0 on failure

### flickcurl_oauth_get_authorize_uri ()

    char *              flickcurl_oauth_get_authorize_uri   (flickcurl *fc);

Get the URL for the user to authorize Flickr OAuth of an application

Forms the URL the user needs to start at to authorize the application.

This function requires `flickcurl_oauth_create_request_token()` to have been called to build a request token / secret pair.

After this function, the application should pass the verifier to `flickcurl_oauth_create_access_token()` for the final step in OAuth along with the request token and request token secret.

`fc` : | flickcurl object
Returns : | authorize URI or NULL on failure

### flickcurl_oauth_create_access_token ()

    int                 flickcurl_oauth_create_access_token (flickcurl *fc,
                                                             const char *verifier);

Get a Flickr OAuth access token from request token credentials and verifier

Calls the Flickr OAuth access token endpoint using the verifier from out of band authentication to get an access token to enable authenticated calls to the Flickr API.

`fc` : | flickcurl object
`verifier` : | verifier from OOB authentication
Returns : | non-0 on failure