Message Token Flow

Message Tokens are UUID4 values that are stored within the tenant's record in the data store. When a new tenant is created a message token should be created and persisted with the new tenant record (see below):

A newly created Tenant record:

{
    "tenant": {
        "tenant_id": "1022",
        "event_producers": [],
	"token": {
	  	"valid": {uuid4},
		"previous": nil
		"last_changed": {current timestamp}
	}
    }
}

Via a REST call you can fetch the tenant's message token either by requesting it directly:

GET /{version}/{tenant_id}/token HTTP/1.1

Expected results:

HTTP/1.1 200 OK
LOCATION: /{version}/{tenant_id}/token

Or, you can get the entire content of the tenant's record:

GET /{version}/{tenant_id} HTTP/1.1

Expected results:

HTTP/1.1 200 OK

{
    "tenant": {
        "tenant_id": "1022",
        "event_producers": [],
	"token": {
	  	"valid": {uuid4},
		"previous": nil
		"last_changed": {timestamp}
	}
    }
}

It is important that we have the ability to invalidate a tenant's message token if need be. This allows a tenant to request that their message token be reset to a new value if they feel the previous message token was compromised.

Resetting a tenant's message token (shown with an optional JSON payload):

POST /{version}/{tenant_id}/token HTTP/1.1

{
	"token": {
		"invalidate_now": true
	}
}

The optional JSON payload allows a tenant to override the default time period invalidation process. Normally when a message token is reset the current message token value will be moved to the previous value and the timestamp will be updated to a current timestamp value.

Here is the default message token invalidation flow:

Before

{
    "tenant": {
        "tenant_id": "1022",
        "event_producers": [],
	"token": {
	  	"valid": "95ACC954-3B19-459C-9CF7-8A4E84CF4953",
		"previous": nil
		"last_changed": {timestamp}
	}
    }
}

Tenant initiates a request to invalidate their message token (Note: This is not an immediate invalidation request):

POST /{version}/{tenant_id}/token HTTP/1.1

After

{
    "tenant": {
        "tenant_id": "1022",
        "event_producers": [],
	"token": {
	  	"valid": "5B838B98-49FC-4CAA-807A-9E7B4F7EBEB4",
		"previous": "95ACC954-3B19-459C-9CF7-8A4E84CF4953"
		"last_changed": {current timestamp}
	}
    }
}

Here is the the token invalidation flow when the Tenant initiates a request to invalidate their message token immediately:

Before

{
    "tenant": {
        "tenant_id": "1022",
        "event_producers": [],
	"token": {
	  	"valid": "95ACC954-3B19-459C-9CF7-8A4E84CF4953",
		"previous": nil
		"last_changed": {timestamp}
	}
    }
}

Tenant initiates request for immediate message token invalidation:

POST /{version}/{tenant_id}/token HTTP/1.1

{
	"token": {
		"invalidate_now": true
	}
}

After

{
    "tenant": {
        "tenant_id": "1022",
        "event_producers": [],
	"token": {
	  	"valid": "DA4CA397-0067-4F0D-9BFB-1720857D0770",
		"previous": nil
		"last_changed": {current timestamp}
	}
    }
}

Tenant's expected response from the request to invalidate the message token:

HTTP/1.1 203 NON-AUTHORITATIVE INFORMATION
LOCATION: /{version}/{tenant_id}/token

There is some criteria to be aware of if they are not immediately invalidating their message token. Message tokens cannot be changed within a three hour time period. If they attempt to change a message token within the three hour time period an HTTP 409 (and a user friendly message) will be thrown like so:

HTTP/1.1 409 CONFLICT
CONTENT-TYPE: application/json

{ 
    "message": "Message tokens can only be changed once every three hours"
}