All URIs are relative to https://localhost
| Method | HTTP request | Description |
|---|---|---|
| get_token | POST /oauth/token | Get tokens |
| revoke_token | POST /oauth/revoke | Revoke a token |
AccessToken get_token(grant_type, client_id, client_secret, refresh_token=refresh_token, username=username, password=password)
Get tokens
finAPI implements the OAuth 2.0 Standard for authorizing applications and users within applications. OAuth uses the terminology of clients and users. A client represents an application that calls finAPI services. A service call might be in the context of a user of the client (e.g.: getting a user's bank connections), or outside any user context (e.g.: editing your client's configuration, or creating a new user for your client). In any case, every service call must be authorized by an access_token. This service can be used to get such an access_token, for either one of the client's users, or for the client itself. Also, this service can be used to refresh the access_token of a user that has previously requested an access_token.
To get a token, you must always pass a valid client identifier and client secret (=client credentials). You can get free client credentials for the sandbox here. Alternatively, you can also contact us at [email protected].
The authorization process is similar for both a user within a client, and for the client itself:
• To authorize a client (i.e. application), use grant_type=client_credentials
• To authorize a user, use grant_type=password
If the given parameters are valid, the service will respond with the authorization data.
Here is an example of a response when authorizing a user:
{ "access_token": "yvMbx_TgwdYE0hgOVb8N4ZOvxOukqfjzYOGRZcJiCjQuRGkVIBfjjV3YG4zKTGiY2aPn2cQTGaQOT8uo5uo7_QOXts1s5UBSVuRHc6a8X30RrGBTyqV9h26SUHcZPNbZ", "token_type": "bearer", "refresh_token": "0b9KjiBVlZLz7a4HshSAIcFuscStiXT1VzT5mgNYwCQ_dWctTDsaIjedAhD1LpsOFJ7x6K8Emf8M3VOQkwNFR9FHijALYSQw2UeRwAC2MvrOKwfF1dHmOq5VEVYEaGf6", "expires_in": 3600, "scope": "all" }Use the returned access_token for other service calls by sending it in a 'Authorization' header, with the word 'Bearer' in front of the token. Like this:
Authorization: Bearer yvMbx_TgwdYE0hgOVb8N4ZOvxOukqfjzYOGRZcJiCjQuRGkVIBfjjV3YG4zKTGiY2aPn2cQTGaQOT8uo5uo7_QOXts1s5UBSVuRHc6a8X30RrGBTyqV9h26SUHcZPNbZ
WARNING: Sending the access_token as a request parameter is deprecated and will probably be no longer supported in the next release of finAPI. Please always send the access_token in the request header, as shown above.
By default, the access tokens have an expiration time of one hour (however, you can change this via the service PATCH /clientConfiguration). If a token has expired, then using the token for a service call will result in a HTTP code 401. To restore access you can simply get a new token (as it is described above) or use grant_type=refresh_token (which works for user-related tokens only). In the latter case you just have to pass the previously received refresh_token for the user.
If the user that you want to authorize is not yet verified by the client (please see the 'isUserAutoVerificationEnabled' flag in the Client Configuration), then the service will respond with HTTP code 403. If the user is locked (see 'maxUserLoginAttempts' in the Client Configuration), the service will respond with HTTP code 423.
If the current role has no privileges to call a certain service (e.g. if a user tries to create a new user, or if a client tries to access user data outside of any user context), then the request will fail with the HTTP code 403.
IMPORTANT NOTES:
• Even though finAPI is not logging query parameters, it is still recommended to pass the parameters in the POST body instead of in the URL. Also, please set the Content-Type of your request to 'application/x-www-form-urlencoded' when calling this service.
• You should use this service only when you actually need a new token. As long as a token exists and has not expired, the service will always return the same token for the same credentials. Calling this service repeatedly with the same credentials contradicts the idea behind the tokens in OAuth, and will have a negative impact on the performance of your application. So instead of retrieving the same tokens over and over with this service, you should cache the tokens and re-use them as long as they have not expired - or at least as long as you're using the same tokens repeatedly, e.g. for the time of an active user session in your application.
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint
# create an instance of the API class
api_instance = swagger_client.AuthorizationApi()
grant_type = 'grant_type_example' # str | Determines the required type of authorization:password - authorize a user; client_credentials - authorize a client;refresh_token - refresh a user's access_token.
client_id = 'client_id_example' # str | Client identifier
client_secret = 'client_secret_example' # str | Client secret
refresh_token = 'refresh_token_example' # str | Refresh token. Required for grant_type=refresh_token only. (optional)
username = 'username_example' # str | User identifier. Required for grant_type=password only. (optional)
password = 'password_example' # str | User password. Required for grant_type=password only. (optional)
try:
# Get tokens
api_response = api_instance.get_token(grant_type, client_id, client_secret, refresh_token=refresh_token, username=username, password=password)
pprint(api_response)
except ApiException as e:
print("Exception when calling AuthorizationApi->get_token: %s\n" % e)| Name | Type | Description | Notes |
|---|---|---|---|
| grant_type | str | Determines the required type of authorization:password - authorize a user; client_credentials - authorize a client;refresh_token - refresh a user's access_token. | |
| client_id | str | Client identifier | |
| client_secret | str | Client secret | |
| refresh_token | str | Refresh token. Required for grant_type=refresh_token only. | [optional] |
| username | str | User identifier. Required for grant_type=password only. | [optional] |
| password | str | User password. Required for grant_type=password only. | [optional] |
No authorization required
- Content-Type: Not defined
- Accept: application/json
[Back to top] [Back to API list] [Back to Model list] [Back to README]
revoke_token(token, token_type_hint=token_type_hint)
Revoke a token
An additional endpoint for the OAuth 2.0 Standard, which allows clients to notify finAPI that a previously obtained refresh_token or access_token is no longer required. A successful request will invalidate the given token. The revocation of a particular token may also cause the revocation of related tokens and the underlying authorization grant. For token_type_hint=access_token finAPI will invalidate only the given access_token. For token_type_hint=refresh_token, finAPI will invalidate the refresh token and all access tokens based on the same authorization grant. If the token_type_hint is not defined, finAPI will revoke all access and refresh tokens (if applicable) that are based on the same authorization grant.
Note that the service responds with HTTP status code 200 both if the token has been revoked successfully, and if the client submitted an invalid token.
Note also that the client's access_token is required to authenticate the revocation.
Here is an example of how to revoke a user's refresh_token (and therefore also his access tokens):
Authorization: Bearer {client_access_token} POST /oauth/revoke?token={refresh_token}&token_type_hint=refresh_token
from __future__ import print_function
import time
import swagger_client
from swagger_client.rest import ApiException
from pprint import pprint
# Configure OAuth2 access token for authorization: finapi_auth
configuration = swagger_client.Configuration()
configuration.access_token = 'YOUR_ACCESS_TOKEN'
# create an instance of the API class
api_instance = swagger_client.AuthorizationApi(swagger_client.ApiClient(configuration))
token = 'token_example' # str | The token that the client wants to get revoked
token_type_hint = 'token_type_hint_example' # str | A hint about the type of the token submitted for revocation (optional)
try:
# Revoke a token
api_instance.revoke_token(token, token_type_hint=token_type_hint)
except ApiException as e:
print("Exception when calling AuthorizationApi->revoke_token: %s\n" % e)| Name | Type | Description | Notes |
|---|---|---|---|
| token | str | The token that the client wants to get revoked | |
| token_type_hint | str | A hint about the type of the token submitted for revocation | [optional] |
void (empty response body)
- Content-Type: Not defined
- Accept: application/json
[Back to top] [Back to API list] [Back to Model list] [Back to README]